Ask HN: Best tool or method to document large software projects? | Hacker News Reader

Ask HN: Best tool or method to document large software projects?

12 pointsalexfromapex7 comments

If you are on a team of say 80 engineers, working on a large product, in different departments and teams, how do you ensure good documentation and communication/transparency with all team members?

View on HN

1. Start by understanding that this is a primarily social problem. Techniques like documentation or microservices are only that: techniques. The real goal is clear communication by any means necessary.

2. Make it easy to see from a document when it has gone out-of-date and whom to ask about it. If you expect a document to stay up-to-date, make sure someone has the capacity to pay attention to to and answer questions.

3. Less, but better. Actively encourage the process of pruning docs and putting them in history so that what remains stays trusted.

4. Start with Why. The most important thing to document is why things are. Why teams exist. Why projects exist.

5. Don’t assume that everyone has the context to write or maintain every document. If an individual is trying to create clarity on the organization’s top-level goals... then something deeper is broken.

6. Docs are best written as a pair-programming exercise between a novice and a senior.

If the audience is other developers/engineers (which it sounds like it is)... I like to document the code within the code itself and use automation to generate that documentation. If it fails to generate or documentation is missing, the pipeline itself will fail and prompt the developer to write docs before it gets merged.

I'm usually programming in Ruby or Golang. For Ruby my tool of choice is the Yard gem... and for Golang it would be GoDoc (built into Go itself). But most languages have their own equivalent tools.

If the audience is business folks and not developers... oofffpppph.

Documentation about development workflow processes or ways to do things can be separate. Documentation on how a particular piece of software works and why should be in-band. Commit it with the source code. Keeping them as close as possible makes it the easiest to discover and keep in sync. A quick edit and check-in with the code changes is so much easier than remembering to to a second pass in another repo after changes were already 'done'.

Create a repository dedicated to that. Use something like Markdown Notes VS Code extension to make a fast to write wiki with [[wiki-link]]s

https://marketplace.visualstudio.com/items?itemName=kortina....

Let people contribute to the doc just like any piece of software.

https://docusaurus.io/

Make it a priority. Really emphasize that it is a priority. You can start by providing some of the documentation yourself (via whatever system it is you use). The tool is irrelevant.

What falls through the cracks?

Reply on news.ycombinator.com