Ask HN: How Do You Write Documentation | Hacker News Reader

Ask HN: How Do You Write Documentation

42 pointsOliverGilan18 comments

Hello HN, I'm a new grad fresh out of college who just started my first gig as a software engineer. My team currently has very few docs for their codebases and it lead to quite a difficult and long onboarding process. Good documentation has always been an incredible help for me while in school and working on side projects but I've never really learned or put in the effort to WRITE good documentation myself. I think my team could really use a revamp in their documentation and I would love to be the one to provide that but I don't even consciously know what separates good docs from bad docs.

Are there specific "design principles" for writing documentation? For example, what sections should there be, how should the info be structured, etc.

When it comes to diagrams, UML seems like the framework to learn but are there others?

Btw, these would be internal and not public facing. Thanks!

View on HN

I write the kind of documentation that would help me to get to know a codebase quickly.

- Architecture: what modules are there, what are their responsibilities? What is in scope and out of scope (non-goals are super important). Keep this short and sweet.

- Tutorials: Show how to do some common tasks with the code. A good way to communicate intended life cycles and best practices.

- Reference: Details. I feel API contracts are the most important. I prefer trying to eliminate this type as much as possible, by trying to make invalid usage unrepresentable. If your team uses IDEs, consider putting this in a format that shows up in autocomplete/inline docs. How much you need this depends a lot on if you're working with dynamic or static types.

This may or may not be what you need: Four kinds of documentation https://documentation.divio.com/ (In short: tutorials, how-to guides, technical reference and explanation.)

Discussed at https://news.ycombinator.com/item?id=21289832.

Edit: Apparently discussed again at https://news.ycombinator.com/item?id=26002656.

In a good documentation, IMHO, you must answer the following questions:

  - where can I find this functionality?
  - how is it done?
  - why is it done this way?

You can do a lot with descriptive schemas, take a look at C4 models[1], they are simpler than UML and focus on a single part of your project at a time. This should answer the "where".

Tutorials are a good way to present a use case and how to solve it using your project. This should answer the "how".

Then, the most difficult part for me are ADR[2] (Architectural Decision Record), to document all decisions within the project. This should answer the "why".

EDIT NB: Our ADR is our PRs since committing directly to master/main is forbidden and all code should be reviewed

API Documentation is then done with comments/docstrings within the code itself, and usually the IDE knows how to read it and help you directly while you write code.

[1] - https://c4model.com/

[2] - https://adr.github.io/

Have a look here: „A framework for writing documentation“. [1]

[1] https://news.ycombinator.com/item?id=26002656

Just from the top of my head:

For internal docs, focus more on “why”. Explain why the software exists & what problem it solves. Why the design decisions were made. Why the trade offs were good (at the time, since systems change and evolve).

If you have meeting notes, attach it as an appendix with list of stakeholders involved.

List known dependent services and clients.

Start with the big picture and describe the interaction between components/services. Then have each section drill down into the components.

If this is a wiki page or a living document, add links to various dashboards, metrics, CI/CD, repos, Jira, etc. list of stakeholders.

If this is internal to the company but other teams can access it, have a section on how others team can do some preliminary debugging. How to contact your team (ticket? Slack? Email?).

In general, I don’t think I’ve seen bad documentation per se. any documentation helps. It’s just that they get outdated and become misleadinng. Instead of focusing on wiring a perfect doc the first time, I think it’s more important to keep it up to date.

The key to good documentation is the will to write documentation. The tools are not lacking, the will is lacking.

I strongly disagree. I've seen a lot of bad documentation, that doesn't bring any benefit. Sometimes it even hides important information, because there was just so much crappy information collected and put together, so nobody understands it anymore.

So before you start, think about what you need to document and why.

FWIW, documentation isn’t very good anywhere. I’ve been at many companies, and it’s always been varying levels of mediocre to bad, even with a dedicated team of documentation writers.

My recommendations are:

- DO Try to rally the whole team to contribute. Attempting to write useful documentation yourself for more than one or two other people’s code is a Sisyphean task.

- DO Make documentation (and testing and debugging) part of the job and the culture of programming. The best documentation is written by the same person that wrote the software. In my experience, it’s surprising how often I bump into programmers who believe that testing and docs are not part of their job.

- DONT try to document everything. There’s too much. There are too many people writing code faster than you can document (especially if they’re not documenting along the way). It’s also unnecessary, most code is only seen by the people that wrote it, most code doesn’t need separate written documentation aside from code comments. Focus on the documentation that is most needed by the widest audience.

- DO Focus on a small number of specific workflows, like onboarding, and gather continuous feedback on your documentation from the people who use it.

- DO Establish a plan to version your docs and more importantly to delete old and obsolete documentation. Having a massive sea of outdated docs has been half the problem in my experience, old docs can be confusing and misleading, and having to wade through them to find the right stuff wastes time and energy.

Start from the outside in. What interfaces does the system have? What are their purposes? How and where does the system store data? What executables are there? What are their purposes? Why was it separated as it is? What communication channels are there between the executables? For the more complicated executables, what components do they have and how do these interact? Why are these components as they are and not different? This is kind of a hierarchical breakdown that would map quite well into parts, chapters and sections of a document. From that level downwards there should be comments for non-obvious pieces of code. Often the birds-eye-view is what is lacking. One should also be cautious of existing documentation and of people telling you how things are. Often things are stated with great confidence that are not completely true or not true at all or used to be true but are no longer. This is also a danger of any documentation that you would be writing. If you are not keeping it up-to-date and also making sure that people have a way of finding whatever information they need, it might just be a better idea to not write documentation at all.

Firstly make sure you split the docs into the 4 categorise others have mentioned. For internal use, a great reference is usually where you want to get started. After that you should be able to put together an explanation of the bigger concepts. If you need to draw diagrams, Lucidcharts is really easy to get the job done.

Just sharing what worked for us. Lowdefy docs [1] was written in Lowdefy. It makes is really simple to get markdown on a page. Would also be possible to write a script to generate the docs from code. But as far as I can tell, the code is not documented either. For the Lowdefy blocks we only write JSON-schemas but then convert that with a simple script to what you see in the docs.

[1] - https://docs.lowdefy.com

First off when you say:

> My team currently has very few docs for their codebases

Note this is the default state in most companies and organizations, so don't feel you have an especially bad deal.

> [...] but I've never really learned or put in the effort to WRITE good documentation myself.

There are no special skills required to WRITE docs, other than to simulate what info the ppl who will READ the docs might need. So in a way, your past experience reading good docs optimally prepared you to write docs now.

Overall I think you have an interesting opportunity to add docs to various projects you will be involved in (very worthwhile experience to write things up to understand, and help future onboarding of collegues, but also to help with extraction and exchange of info within existing team.

My recommendations would be to start in the following order:

1. README.md in each repo with ##Installing and ##Running sections (avg. dev setup should not require a meeting or support—REDME should be self sufficient)

2. Data models info (since code bases can be 100k+ lines of code and you have NO chance of understanding right away, you can start by looking the DB tables. Ideally export the schema from a production DB so have latest info. Look for tools to help you extract info and transfer to a shared spreadsheet where can be further annotated.

3. API endpoints. You don't need to document everything, but if you can get a list of all endpoints for a service it can be very helpful (`./manage.py show_urls` in Django if you have django-extensions installed).

4. System diagrams. This is not really for you as a beginner to do, but maybe you can ask some of the more expreinced teammates to draw an overview diagram of services and interactions (think box-levle diagrams like business people would use in slides, not detailed). You can volunteer to turn hand-drawn summaries into nice diagrams to use in docs (this kind of birds-eye overview diagrams are very useful for beginners, and generally low maintenance since don't have details).

My top down approach for writing software design docs: 1. Business objectives 2. Users and use cases 3. Architecture <- design decision, performance expectation, wide picture of the system 4. Infrastructures <- you may mention environment and networks here, like k8, aws or gcp. 5. Application <- ui, flow, activity diagram, algorithm here 6. Data <- now you can place UML here

As for code level documentation, writing readable codes is enough as documentation. If some guys can understand what the codes do by reading the codes, documentation won't be needed. How to write readable codes? A good reference for this is Clean Code book. If documentation is really needed, Java Doc style is worth to follow.

Hope this helps

Recent discussion on architecture documentation https://news.ycombinator.com/item?id=26048784

for documentation, I found it's helpful to think of what you're trying to accomplish

theres a fantastic talk about the 4 types of documentation (https://www.kevinslin.com/notes/89cefe18-cc6e-423e-8876-bc57...) which i've listed below: - tutorials - how to guides - explanations - references

for internal software teams, I found explanation and references to be the most useful. in case you were also looking for a documentation tool, check out http://dendron.so. its an open source note-taking tool build for developers and is integrated with vscode, markdown and git. plus it can compile to static html which you can host internally (disclaimer: I'm the founder)

First you need to know what kind of documentation you want to write.

I am a developer and I mostly write documentation for my code and the projects I'm working for. The audience for the documentation is mostly other developers and technical people who use the software.

So for every project or module I develop/work on, i try to answer those questions:

  - What is this software doing?
  - Why does it exists?
  - What problem does it solve?
  - Where does it fit in?

And next some more practical questions:

  - How do I build it?
  - How do I test it?
  - How do I deploy it?
  - What dependencies do I need, and where can I get them?

If you have build scripts, CI scripts or Docker files, link them, they are most of the time the best documentation for those processes.

This part already helps a lot, and answers a lot of questions to get other developers started.

I try to make my code as readable as possible, so it doesn't need a lot of documentation. A lot of documentation can be really bad, when you do changes. Because you also need to change a lot of documentation. ALWAYS update the documentation if you change the code. At least delete outdated documentation, if you don't have time to update it.

If I write documentation, I try to answer the questions that are not obvious, and skip the obvious ones, that can be figured out from the code

Bad: The `StockPriceLoader` loads stock prices

Good: The `StockPriceLoader` fetches data from `StockPriceProviders` (see folder ../spp/implementation) and writes them into the database table `stock_prices`

If there are some complex processes I try to make flowcharts for that (but don't overdo it!). I mostly write README.md, my choice there is mermaid or plantuml, which can be directly rendered by some Markdown renderers (Gitlab or VS Code Markdown Preview Enhanced for example).

I try to put the documentation as close as possible to the source code. Mostly directly into the same folder where the code is. So you get versioning for your documentation for free, and if you pull an old version of your code, you get the corresponding documentation.

If you're creating libraries or interfaces, completely different rules will apply. You are probably going to need a complete API documentation, examples, tutorials, ...

At some point you probably need different kind of manuals too: or the end user, for operations, for 1st level support, fact sheets for sales, ...

Mason Egger's talk on the topic is transformative: https://www.youtube.com/watch?v=4SwdVMKhbn4

On a similar problem, does anyone have any wiki software they use for long-term knowledge aggregation?

I've found that the brain is the best at long-term knowledge aggregation.

Because it all boils down to retrieving the information. And the brain is very efficient at retrieving information quickly (I can recite poems learnt in school 20 years ago).

I've always had difficulties organizing a Wiki, so instead I try to remember "where" I found the information (which is often easier than remembering the information itself).

Instead of looking for a wiki software, look for a search engine and index your knowledge in that search engine.

Reply on news.ycombinator.com