I have been working on updating my “production” environment for the last month and a bit now and now that I have most of the core up and running it is time for me to look at a better way to store and manage my documentation.
Currently, I have been using LibreOffice to make various documents, spreadsheets and drawings to document the production environment and keep login credentials in a KeepassXC database. This system has worked for a number of years now but does not allow me to track changes or reuse templates very efficiently, and probably not the most effective solution.
I have looked at using a Wiki but not sure that It will be the right fit in terms of ease of use for non-technical types or allow me to properly document network diagrams or rack diagrams. I played around with Bookstack and found it was almost there but did not allow for easy import and export of data and also seemed to be missing a layer of the organization structure (like being able to create bookcases to place the shelves on). I also looked at SuiteCRM but it had many many features I would never use and seemed to be overkill for just a documentation server (though I was planning to use other applications for things like invoicing, tickets and other related tasks), and I also did not want to have to expose the documentation server and make it public-facing. If i were to combine everything into one server it could not isolate specific sections from being public-facing.
I spent the better part of today to try and build and Nextcloud install with ONLYOFFICE as another possible solution but could not get ONLYOFFICE to work at all.
Does anyone in the community have any recommendations for a solution or insight on what solutions they are using, ideally with a link to an install/configuration guide I could follow to set up a test server and see how that particular solution works and would fit my needs.
http://www.sphinx-doc.org/en/master/
This is the tool used to make Pfsense Book.
You need a version control to keep track of all documents versions. Like GIT.
The theory behind this is that:
You decople content from formating.
If you use Word or some other word processor, you will be dealing with format a lot of the time instead of deling for content.
- Write chapters like text files using simple conventions required by Sphinx. Focussing in content, not format.
- You use a simple text editor or something like VisualStudio Code.
- Keep track of versions with GIT.
4 You select a template you like for Sphinx. (I like the one they used for PFsense Book)
5 You “compile” your document and you get a HTML you can upload to a webserver (like PFSense Book) or a PDF, or other formats.
It looks like a a lot of work, but this way you can produce documentation of thousand of pages.
Other tools you can use is Latex, but the learning curve is too steep. Sphinx uses Latex internaly when compiling PDFs.
Of course there are systems but this option is free.
Is also worth a look, used for generating:
After trying to get Collabora online and Only Office working for almost a week and re evaluating my documentation needs and wants I ended up going with Bookstack.
My concern of being able to import and restore data is solved 2 ways, one i can export entire books as PDFs as a backup copy and also export a HTML file that can be rebuilt by exiting the source of a page in Bookstack so just become a copy paste game for now to restore a page from the html source. The second way is that Bookstack is running in a VM which is backed up each day so I can restore the entire machine should there be a larger issue than a few pages.
I would still like another layer of organization but have been able to work round that limitation by re structuring my documentation a little bit and in some areas has been a great improvement over my old way.