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

The case for continuous documentation

virtuallifestyle.nl

Post reply on HN
Print view View original

11–20 of 71 posts

Re: The case for continuous documentation

#11

Post by klohto »

Noumenon72 wrote: post #9
simonw wrote: post #4

I'm adamant that the documentation for a project should live in the same repository as the code itself. This is crucial for a number of reasons: 1. If the docs are in the same repo, a commit that changes the code can update the relevant documentation (in addition to the tests) as part of the same unit of work 2. This means it can be enforced during code review: if a developer forgets to update the docs they can be re…

How do you read the in-repo documentation? Search for all files named readme.md? I have never learned about a library from documentation scattered about the repo. There's the readme at the root, and everything else is on a web page, which is a better way to organize and browse documentation.

Static site generated from the repo. Can be hosted locally or online. Github pages are usually leveraged for this usecase

Re: The case for continuous documentation

#12

Post by petepete »

simonw wrote: post #10
Noumenon72 wrote: post #9

Earlier quoted context omitted.

How do you read the in-repo documentation? Search for all files named readme.md? I have never learned about a library from documentation scattered about the repo. There's the readme at the root, and everything else is on a web page, which is a better way to organize and browse documentation.

I use documentation systems that publish the documentation from the repo to a website. Most of my projects use Sphinx and reStructuredText for this, but I recently tried MyST (Markdown for Sphinx) and I like that a lot. Some examples: - https://docs.datasette.io serves documentation from https://github.com/simonw/datasette/tree/main/docs - which has documentation unit tests here: https://github.com/simonw/datasette/b…

This is definitely the best approach in my opinion, providing the people writing the docs are capable of contributing directly.

One of my projects[0] builds and deploys a static documentation site[1] on every push to master. The static site generator (Nanoc, in this case) imports the library and uses it to publish its own documentation. All the examples are snippets of code[2] that are both displayed as-is and eval'd into the final output.

The guide can never be out of sync with the library.

[0] https://github.com/dfe-digital/govuk_design_system_formbuild...

[1] https://govuk-form-builder.netlify.app/

[2] https://github.com/DFE-Digital/govuk_design_system_formbuild...

Re: The case for continuous documentation

#13

Post by daurnimator »

simonw wrote: post #4

I'm adamant that the documentation for a project should live in the same repository as the code itself. This is crucial for a number of reasons: 1. If the docs are in the same repo, a commit that changes the code can update the relevant documentation (in addition to the tests) as part of the same unit of work 2. This means it can be enforced during code review: if a developer forgets to update the docs they can be re…

None of this works if the programmer isn't the same person that writes the docs. e.g. if you have a copy-writer come along and write/update the docs before each release, then its not captured in the same commit/branch/etc.

Re: The case for continuous documentation

#14

Post by zelphirkalt »

Noumenon72 wrote: post #9
simonw wrote: post #4

I'm adamant that the documentation for a project should live in the same repository as the code itself. This is crucial for a number of reasons: 1. If the docs are in the same repo, a commit that changes the code can update the relevant documentation (in addition to the tests) as part of the same unit of work 2. This means it can be enforced during code review: if a developer forgets to update the docs they can be re…

How do you read the in-repo documentation? Search for all files named readme.md? I have never learned about a library from documentation scattered about the repo. There's the readme at the root, and everything else is on a web page, which is a better way to organize and browse documentation.

If you write your documentation in Emacs org-mode, you could use include [1] to include files on other levels of your repository and then you could export it all to a markdown file for people, who do not know about org-mode and Emacs. This would make documentation anywhere in the repository discoverable / automatically included in your resulting documentation file.

[1] https://orgmode.org/manual/Include-Files.html

Re: The case for continuous documentation

#15

Post by simonw »

daurnimator wrote: post #13
simonw wrote: post #4

I'm adamant that the documentation for a project should live in the same repository as the code itself. This is crucial for a number of reasons: 1. If the docs are in the same repo, a commit that changes the code can update the relevant documentation (in addition to the tests) as part of the same unit of work 2. This means it can be enforced during code review: if a developer forgets to update the docs they can be re…

None of this works if the programmer isn't the same person that writes the docs. e.g. if you have a copy-writer come along and write/update the docs before each release, then its not captured in the same commit/branch/etc.

That can still work, in a couple of ways.

You can have the programmer write bad documentation and file an issue for it to be improved. You can then enforce that releases don't go out until those issues have been resolved by the copywriter.

You can also implement new features in a branch with multiple authors. The branch doesn't get merged until the documentation is in good shape.

Re: The case for continuous documentation

#16

Post by pram »

Documentation is great and all, but no one ever talks about when theres too much. Maybe because it's rare? At big companies I've seen "architects" churn out page after page of diagrams, design docs, runbooks, checklists, descriptions, etc. There is so much information that it becomes practically useless in aggregate, because no one is reasonably going to read it all. I'm not going to pretend that I have the patience or the attention span to have the gnostic mysteries of our Kubernetes infrastructure revealed to me.

Re: The case for continuous documentation

#18

Post by ycombiswimm »

MauranKilom wrote: post #8

I'm a fan of having code samples in the documentation, and making sure (at e.g. build/test time) that those samples actually work . Given the headline, I thought the article would talk about this, but it's more of a general "why and how you should keep your documentation up to date".

The product actually makes sure code samples stay up-to-date when the code changes.

Re: The case for continuous documentation

#19

Post by zelphirkalt »

simonw wrote: post #10
Noumenon72 wrote: post #9

Earlier quoted context omitted.

How do you read the in-repo documentation? Search for all files named readme.md? I have never learned about a library from documentation scattered about the repo. There's the readme at the root, and everything else is on a web page, which is a better way to organize and browse documentation.

I use documentation systems that publish the documentation from the repo to a website. Most of my projects use Sphinx and reStructuredText for this, but I recently tried MyST (Markdown for Sphinx) and I like that a lot. Some examples: - https://docs.datasette.io serves documentation from https://github.com/simonw/datasette/tree/main/docs - which has documentation unit tests here: https://github.com/simonw/datasette/b…

This is a good approach and reStructuredText well suited for technical documentation. The only downside I see in reST is, that it is mostly only readable from the standard implementation in Python, which is a custom parser, not a portable grammar for other languages to implement in any parser tool / library. There are some libraries for parsing it, but last I checked those were incomplete.

Emacs org-mode would be a great candidate as well, for things like runnable code inside the documentation as examples and export to many other formats and nice tooling for viewing the files. Unfortunately many git hosts do not support it well and render crappily.

I would recommend against switching to a non-standard Markdown dialect. Why switch away from reST, which offers all of the things nessecary for a good technical documentation, to some Markdown dialect, which has many important features only bolted on?

That said, one thing I noticed happening with this approach is, that people think "Oh, I have my documentation in my comments of the code! I don't need to write anything else!" And then I end up reading documentation like: "def get_a(): ..." Docstring or comment: "Get a." Wow, thanks, how helpful!

In short: There is no simple way to have good documentation, except for writing good documentation. Docstrings probably will not be sufficient, unless you write whole novels in your docstrings. A good documentation needs usage examples and rationale of why something was done in a specific way, what kind of gotchas there are and probably other stuff, that does not come to mind right now.

Re: The case for continuous documentation

#20

Post by zelphirkalt »

pram wrote: post #16

Documentation is great and all, but no one ever talks about when theres too much. Maybe because it's rare? At big companies I've seen "architects" churn out page after page of diagrams, design docs, runbooks, checklists, descriptions, etc. There is so much information that it becomes practically useless in aggregate, because no one is reasonably going to read it all. I'm not going to pretend that I have the patience…

In such cases I wish for a "cookbook" style of additional documentation, that I can search, to find examples for doing, what I want to do.
Post reply on HN