TL;DR: I have some questions, see bottom of this post.
Hi all,
I'm looking for a simple free tool to host internal documentation at the company where I work that only has about 10 engineers. However, there are so many tools available and I tried a few of them, but I always wonder how well it scales and works in the long term or whether difficulties will arise at some point.
So far, at the company where I work, there's lots of documentation written in Word, text files, and in LaTeX (started by me, bad choice, I was young and naive). It is spread across the company server in different locations, different formats, etc. I believe the will to write documentation is there, but the way it's done is not managable, docs are not kept up to date, docs aren't found by new people, etc.
I understand that 90% of documentation efforts lie in being consistent with writing documentation and keeping it up to date, while the tool used is a second priority. I believe that having the right tool, that has a low threshold for adding or editing existing docs, that can be found and navigated easily, is important. Still, it's an important discussion, but not the one that I intended for this post. Please refrain from making such comments, thank you.
The tool requirements are
- Easy to write/edit/find/navigate
- Low threshold for adding/editing docs
- Supports equations, images, diagrams, code blocks
- Read/write accessible to everyone (also people without git accounts)
- Version controlled
- Free
- As a tool itself, simple to maintain and update
My plan so far is to choose a tool that converts Markdown to HTML. Everyone can write Markdown and it can support equations, images, diagrams, etc. Pages in HTML are easy to read through, can have a table of contents, search bar, whatnot. We version control it in GitLab with a local repository on the shared server. Anyone can just head over to the local repo, add a Markdown file and just leave it there. A select few of us could be assigned as docs admins. One of us could head over every once in a while and review/commit the changes to remote. To publish the changes, we run the tool's `build` command to convert to HTML and we host the static site as a local webserver available within the company. I think this fits the concept called "docs-as-code"?
With a tool that supports this plan, I think this plan supports all requirements. As far as I know, the following tools are a fit:
- Material for MkDocs/Zensical
- Docusaurus
- Starlight (Astro)
- Wiki.js?
- Bookstack?
So now the main point of my post:
I have a few questions which require experience in using these tools, or writing docs in general, which I'd like to ask the citizens of the internet:
- Any flaws in my plan? Pitfalls, or issues that will creep in over time?
- Any other plans that are waaay better?
- Which tool scales well and can properly support hundreds of pages of docs and still be fast to navigate?
- Which tool is easy to maintain, doesn't require dependencies, etc.?
- Which other tools are out there that can do a similar thing, but maybe better?
Thank you!