- They are in an odd separate git repo (.wiki)
- They have to be tied to another ropo
- They can't be published as a website with a URL like ghpages can
- They can't be IP restricted to an organization (maybe this is asking for too much)
What do you use and is it working?
2) Create a Jenkins pipeline that clones your repositories, builds the adoc files, and serves a web index page that you can browse.
3) Execute the pipeline periodically, e.g. once a day.
There, you've got a docs system that is:
- Dev friendly, because they can write docs from their IDEs
- Centralized
- Restricted to whoever has access to Jenkins. So if you put Jenkins behind a VPN, it'll be accessible only there.
I'm sure you can tweak it to give access to some folks to only some pages, though I haven't done that.
- writes a file so you can store it in Git, use the same workflow with branching etc. as the code the documentation documents
- has a GUI so you can just use it like Word etc.
- Free (monetarily) so if I'm using outsourced developers they can all afford it
- Works on Windows, Mac, Linux, so no matter what my developers are using they can use it.
- Can generate PDFs but I don't find that feature (which in a way is its main advertised feature) that useful. Looking at them in LyX on the screen is good enough for me.
We think the best way to keep documentation is along side code and in code, as a docstring. Both to make it more likely that it's updated and also because writing documentation along side code makes it more likely to capture little details that might be missed downstream.
For long form documentation like design, architecture and business considerations writing markdown files and keeping it alongside the section of code it documents works well and is pretty common.
Keeping the docs deployed and updated is a different story and as a lot of people here are doing they're suggesting building CI pipelines to do it.
We decided that's messy so we link in directly to the development flow both with git hooks and IDE integrations.
We then use Github to link what documentation should be allowed to be managed by us and we're working on integrating SSO to manage user onboarding and permissions.
A huge advantage of this approach is that the docs are close to the source and in the most logical place for the relevant stakeholders to benefit from them. This has worked quite well!