Ask HN: How do you keep documentation?
8 comments
1) Make a convention to keep something like docs dir in each of your git repos that contains buildable adoc documentation.
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.
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.
LyX https://www.lyx.org/ Have been using this for all my projects private and commercial for the last 5 years.
- 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.
- 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.
Hey there, I'm a co-founder working on this exact problem.
https://www.docstring.dev/
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.
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.
You should check https://swimm.io/
1. Docs are kept as .MD files in your repos
2. You can use Docusaurus to Publish them
3. They use the Github hierarchy and authorization to decide who has access to the docs.
They are in beta, worth checking
I've kickstarted a docs centralization initiative at my current work, precisely because of all the issues you described.
We have it in version control. There's a top level repo folder called: documentation and inside there are dedicated subfolders for things like onboarding, testing, domain specific tips/knowledge, etc.
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!
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!
I use Obsidian https://obsidian.md/ and track it withing a git repo for my personal projects. The digital garden style works for me and I think it suits the evolving and interconnected nature of documentation. The graph view is a cool feature.
Tiddlywiki
- 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?