Ask HN: How do you organize software documentation at work?

#1

Post by jilles » Wed, Feb 14, 2024, 2:37 PM UTC

Hi folks,

Recently I have ventured into technical writing. At the company I work for, documentation is scattered around ~4 different tools.

1. Google Docs 2. Confluence 3. GitHub (READMEs) 4. Slack

Each of those serves a purpose of course, Google Docs are very collaborative, Confluence is our source of truth, GitHub is mostly for engineering and finally Slack usually has some threads you can find if you run into certain issues.

I am not suggesting we should put all of this into a single tool, but I am wondering if there is a methodology for organizing documentation. I am aware of Diataxis, and want us to use this for certain services / products. What I am looking for in this ASK HN post though, is an overarching methodology of organizing all documentation.

Re: Ask HN: How do you organize software documentation at work?

#2

Post by softwaredoug » Wed, Feb 14, 2024, 2:45 PM UTC

I hate, hate software documentation as a concept. It gets out of date and is hard to use. It's a last resort, only for specialized cases.

I prefer two types of documentation:

1. Executable documentation - tests, asserts, even things like Jupyter notebooks that can be tested and executed

2. Timestamped documentation - documentation that has a clear date on it of when it was valid. So the reader has an expectation "This was true at X date, but may not be true now". This includes detailed pull requests and git commit messages.

https://softwaredoug.com/blog/2023/10/13/fight-undead-docume...

Re: Ask HN: How do you organize software documentation at work?

#3

Post by epirogov » Wed, Feb 14, 2024, 2:48 PM UTC

I wrote important steps for every task to text file, commands, examples, good code snippets. then it simple to remember already researched information for often similar improvements for project codebase.

Re: Ask HN: How do you organize software documentation at work?

#4

Post by coldpie » Wed, Feb 14, 2024, 2:49 PM UTC

Never use a wiki for anything. Wikis are the number one worst form of documentation. They are worse than no documentation. Wikis explicitly destroy the concept of ownership and responsibility, and without those, what you get is a big pile of outdated, unorganized trash that no one maintains. Destroy wikis.

Re: Ask HN: How do you organize software documentation at work?

#5

Post by packetlost » Wed, Feb 14, 2024, 2:50 PM UTC

coldpie wrote: post #4

Never use a wiki for anything. Wikis are the number one worst form of documentation. They are worse than no documentation. Wikis explicitly destroy the concept of ownership and responsibility, and without those, what you get is a big pile of outdated, unorganized trash that no one maintains. Destroy wikis.

So what do you use instead?

Re: Ask HN: How do you organize software documentation at work?

#6

Post by Octabrain » Wed, Feb 14, 2024, 2:52 PM UTC

Where I work, we use Confluence and Backstage. Confluence sucks and Backstage, although I conceptually consider it appealing, sucks too.

Re: Ask HN: How do you organize software documentation at work?

#7

Post by torblerone » Wed, Feb 14, 2024, 2:53 PM UTC

I have yet to see a good documentation strategy. We have quite some awareness about the problem but I don't see an easy exit.

Currently, we have a similar dumpsterfire running. Project / guideline / bla documentation hanging around in Confluence, technical documentation snippets in git repositories "near" the code they belong, some folks scourging themselves with Sharepoint and there's no solution in sight.

Me and some colleagues have developed quite some tendencies against natural language documentation because it basically becomes stale as soon as you publish it into your org.

Re: Ask HN: How do you organize software documentation at work?

#8

Post by stcroixx » Wed, Feb 14, 2024, 2:53 PM UTC

HTML excels at this. Also has the advantage of not depending on a third party with all the compromises that entails.

Re: Ask HN: How do you organize software documentation at work?

#9

Post by quectophoton » Wed, Feb 14, 2024, 2:55 PM UTC

5. Google Meet or Zoom call.

Re: Ask HN: How do you organize software documentation at work?

#10

Post by Zigurd » Wed, Feb 14, 2024, 2:55 PM UTC

Depending on the complexity of the project, short text documents about architecture on Github are OK. Still you have to be careful to document only the most important things that are worth keeping up to date, and then actually doing that.