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

31–40 of 93 posts

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

#31

Post by bmitc »

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.

There are downsides to wikis, but suggesting to never use them is quite extreme. What do you propose instead? Putting everything into the repository doesn't always make sense.

For example, a development setup at a company or group may require a certain setup that depends upon the operating system and IDE/editor an individual developer uses. This type of information is perfect to put on wikis. It is effectively "global" information, whereas repositories contain local information. Putting information like this into a repo can increase the barrier to keeping the documentation updated and also requires source-code control access to view, which not everyone has or should have to view documentation.

In my opinion, a combination of wiki documentation plus documentation within the repository are very good. In addition to that, I often use Google's office suite or Microsoft 365 for working documents, that is documents that need to just be written, get collaborative feedback, shared between external and internal people, etc. Then, once they start to solidify and start to get more atomic updates, it makes sense to move them to the wiki or a Markdown document in a repository.

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

#32

Post by bmitc »

coldpie wrote: post #29
packetlost wrote: post #5

Earlier quoted context omitted.

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.

This doesn't work for documentation that needs to be viewed by people without source-code control access.

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

#33

Post by nwsm »

We use Confluence and markdown files in GitHub. I think we are moving a lot of our docs to Backstage [0] soon.

One process that ends up being really valuable for documentation purposes is our "Architecture Review Documents". This is a standard document that team leads fill out before starting work on a new Saga/Epic/Feature/whatever. It includes the scope and business value of a new feature or large block of work, high level technical architecture of implementation, the impact on existing database schemas and service APIs, etc. This document is presented in a meeting with technical leadership in our organization who deep dive on the topic and explore potential pitfalls in the plan.

The document and recording of that meeting live on forever, and this information is very useful when getting acquainted with a certain part of our product/codebase. You are able to read and hear clearly the intention of a certain service or module, and you can identify several relevant points of contact to ask questions to.

[0] https://backstage.io/

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

#34

Post by bmitc »

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 hate, hate software documentation as a concept. It gets out of date and is hard to use.

My response is almost "too bad". :) Keeping things documented is part of the work, and if it isn't done, then the work is not completed.

Your suggestions of (1) and (2) are great suggestions to have as components to the documentation system. Notebooks are really fantastic for this.

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

#35

Post by sshine »

coldpie wrote: post #29
packetlost wrote: post #5

Earlier quoted context omitted.

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.

For us, documentation lives in Markdown in Rustdoc comments above the things they document.

There may be longer write-ups, examples, etc. at the module level.

Documentation gets compiled into a docs.rs-style searchable website like so:

https://docs.rs/tokio/1.36.0/tokio/

Examples are compiled and run as part of the default CI toolchain.

So when a piece of documentation refers to some code that was moved or renamed, it is a bug to not update references in Rustdoc comments.

Comments can still get stale because some programmers write but don't read.

But they're right there on your screen next to the code you're updating.

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

#36

Post by coldpie »

bmitc wrote: post #32
coldpie wrote: post #29

Earlier quoted context omitted.

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.

This doesn't work for documentation that needs to be viewed by people without source-code control access.

Sure it does. As part of your CI process, build your markdown into HTML or whatever and host it.

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

#37

Post by coldpie »

bmitc wrote: post #31
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.

There are downsides to wikis, but suggesting to never use them is quite extreme. What do you propose instead? Putting everything into the repository doesn't always make sense. For example, a development setup at a company or group may require a certain setup that depends upon the operating system and IDE/editor an individual developer uses. This type of information is perfect to put on wikis. It is effectively "globa…

Five years and 80% employee turnover from now, your wiki will be a completely unsearchable pile of outdated trash from employees who don't work there anymore. Wikis are not documentation, they are dumpsters you can rummage through and try to find a nugget of wisdom. Don't make your new employees rummage through dumpsters.

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

#38

Post by bmitc »

coldpie wrote: post #36
bmitc wrote: post #32

Earlier quoted context omitted.

This doesn't work for documentation that needs to be viewed by people without source-code control access.

Sure it does. As part of your CI process, build your markdown into HTML or whatever and host it.

Slack message received: "Hey, I was reading the documentation and walking through the process and encountered this and this . Can you fix and re-export the documentation? Thanks!"

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

#39

Post by saccharose »

arc42 [1], rendered into whatever format you prefer for reading. In our case we write asciidoc (sometimes markdown) and render it to HTML for each of the releases, so that a version of the documentation is delivered with the release. The authors of arc42 also encourage users to set documentation under version control to ensure one can keep the project and its documentation in sync [2].

[1] https://arc42.org/overview [2] https://faq.arc42.org/questions/G-1/

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

#40

Post by bmitc »

coldpie wrote: post #37
bmitc wrote: post #31

Earlier quoted context omitted.

There are downsides to wikis, but suggesting to never use them is quite extreme. What do you propose instead? Putting everything into the repository doesn't always make sense. For example, a development setup at a company or group may require a certain setup that depends upon the operating system and IDE/editor an individual developer uses. This type of information is perfect to put on wikis. It is effectively "globa…

Five years and 80% employee turnover from now, your wiki will be a completely unsearchable pile of outdated trash from employees who don't work there anymore. Wikis are not documentation, they are dumpsters you can rummage through and try to find a nugget of wisdom. Don't make your new employees rummage through dumpsters.

Just because someone is bad at curating documentation doesn't mean it is inherent to wikis. Wikis and repository-sourced documentation are under the same constraints of requiring curation. There is no "automatic" documentation that happens. It has to be written, updated, maintained, and publicized.

People's problems with documentation are they don't want to deal with it. It's usually not about the systems used to document things.

Post reply on HN