Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

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

news.ycombinator.com

Post reply on HN
Print view View original

21–30 of 93 posts

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

#21

Post by PeterisP »

Our projects have a certain need for documentation that describes the exact meaning of various data fields in files/APIs/DB entries, etc.

We have decided that the best place for the "single source of truth" for that is right next to the appropriate code in git, with the various build/deployment scripts ensuring that copies (explicitly unmaintained, unmaintainable, read-only) of that get packaged with the actual systems, with the packaged libraries, linked in their web backends, etc. We don't care much about the format of the document, whatever fits the particular needs best - e.g. sometimes it's markdown, sometimes it's Excel.

The key factor here is to ensure that (a) there's a single source of truth; (b) you can have the same atomic commit/pullrequest/whatever altering both the system and the documentation at the same time; (c) every artifact has the appropriate version of the documentation, instead of going to some internal site or document which might have a different, newer version, you know what is supposed to be true for this release which actually is on this particular server.

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

#22

Post by softwaredoug »

simonw wrote: post #12
softwaredoug wrote: post #2

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 "Thi…

I think there's a solution for avoiding zombie documentation. The documentation lives in the same git repository as the code that it documents. Inaccuracies or out-of-date documentation is treated as a severe bug. Issues are filed, the documentation gets fixed. This is crucial, because if zombie documentation is allowed to persist it causes people to lose trust in the documentation, which means they won't refer to it…

Seems like a great problem for LLMs to help solve as well :)

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

#23

Post by laylower »

simonw wrote: post #12
softwaredoug wrote: post #2

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 "Thi…

I think there's a solution for avoiding zombie documentation. The documentation lives in the same git repository as the code that it documents. Inaccuracies or out-of-date documentation is treated as a severe bug. Issues are filed, the documentation gets fixed. This is crucial, because if zombie documentation is allowed to persist it causes people to lose trust in the documentation, which means they won't refer to it…

For simpler code, can't the solution be a human-enhanced LLM output?

1) LLM scans code updates and approximates output 2) Developer reviews and updates if needed 3) Feed back tagged code and updated output to LLM 4) ? 5) Profit

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

#24

Post by laylower »

softwaredoug wrote: post #22
simonw wrote: post #12

Earlier quoted context omitted.

I think there's a solution for avoiding zombie documentation. The documentation lives in the same git repository as the code that it documents. Inaccuracies or out-of-date documentation is treated as a severe bug. Issues are filed, the documentation gets fixed. This is crucial, because if zombie documentation is allowed to persist it causes people to lose trust in the documentation, which means they won't refer to it…

Seems like a great problem for LLMs to help solve as well :)

We should...talk.

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

#25

Post by madduci »

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 stop using Confluence?

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

#27

Post by CoastalCoder »

simonw wrote: post #12
softwaredoug wrote: post #2

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 "Thi…

I think there's a solution for avoiding zombie documentation. The documentation lives in the same git repository as the code that it documents. Inaccuracies or out-of-date documentation is treated as a severe bug. Issues are filed, the documentation gets fixed. This is crucial, because if zombie documentation is allowed to persist it causes people to lose trust in the documentation, which means they won't refer to it…

I tried to get this going on an open source project I worked with, and found basically no support from the other contributors.

I think it basically came down to incentives. Those who were developing the code every day had all the relevant details in their heads. So ensuring that docs matched the code was basically a distraction from their primary goals.

It makes me a little angry because it screws over users of the software. The docs don't even mention that they might be out of date.

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

#29

Post by coldpie »

packetlost wrote: post #5
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?

The same tool you use for merging code, with the same ownership & maintainer model. In our case, that's git, and our docs live in markdown files in a docs/ folder.

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

#30

Post by robertlagrant »

simonw wrote: post #12
softwaredoug wrote: post #2

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 "Thi…

I think there's a solution for avoiding zombie documentation. The documentation lives in the same git repository as the code that it documents. Inaccuracies or out-of-date documentation is treated as a severe bug. Issues are filed, the documentation gets fixed. This is crucial, because if zombie documentation is allowed to persist it causes people to lose trust in the documentation, which means they won't refer to it…

> Inaccuracies or out-of-date documentation is treated as a severe bug. Issues are filed, the documentation gets fixed.

Why does this work with Git but not with non-Git? Being in Git doesn't seem to relevant to raising documentation bugs as bugs.

Post reply on HN