The case for continuous documentation • Hacker News Board

Re: The case for continuous documentation

#41

Post by iamEAP » Sun, Jun 06, 2021, 5:44 PM UTC

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.

Check out Backstage, and in particular, TechDocs: https://backstage.io/docs/features/techdocs/techdocs-overvie...

Re: The case for continuous documentation

#42

Post by dllthomas » Sun, Jun 06, 2021, 6:23 PM UTC

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…

> a test that fails if a new API endpoint isn't mentioned [...]

That's a great idea. A related thought I had was testing assertions about architecture by looking at the graph of imports or calls.

From your blog post,

> if a change doesn’t update the relevant documentation, point that out in your review!

What you get at but don't seem to state explicitly is that finding the relevant documentation is hard, for both the author and reviewer. Finding any relevant documentation should be easy, but ideally we're finding all relevant documentation, and we need to be reaching sufficient confidence that we're missing little enough that we're able to hold back entropy enough to keep the docs useful.

Your tools address this for some cases! Doctest addresses this for other cases. From TFA here, it sounds like Swimm.io tries to address this for more cases (my gut says the article oversells it but I intend to look more closely).

To get further, an idea I've been toying with is to treat claims (implicit or explicit) in documentation as requiring citation, pointing not at sources but at tests. Ideally the test runner, when a test fails, can then surface all references to that test. In addition to highlighting portions of the docs that may need to change, this seems likely to also provide crucial context when fixing the code and/or the test.

Re: The case for continuous documentation

#43

Post by dllthomas » Sun, Jun 06, 2021, 7:01 PM UTC

deeblering4 wrote: post #37

Oh cool, so books and websites in general are “bad” now.

Not, by this metric, if they live in the same repo as the code. When they don't, they have the same problem as any strongly coupled systems maintained across multiple repos, or you are paying the cost of keeping the two uncoupled.

Re: The case for continuous documentation

#44

Post by simonw » Sun, Jun 06, 2021, 7:17 PM UTC

zelphirkalt wrote: post #19

simonw wrote: post #10

Earlier quoted context omitted.

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 g…

"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?"

Honestly, the main reason is that I've encountered developers who have an almost alergic reaction to rST - they genuinely hate writing in it, and will be deterred from writing documentation if they have to figure it out.

Custom Markdown flavours are more likely to get buy-in.

Re: The case for continuous documentation

#45

Post by tanaypingalkar » Sun, Jun 06, 2021, 8:05 PM UTC

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…

Is there any lib/way that automatically generate doc for api/endpoint. I think it is possible to create such generator for graphql api.

Re: The case for continuous documentation

#46

Post by simonw » Sun, Jun 06, 2021, 8:28 PM UTC

CraigJPerry wrote: post #5

If it's technical docs for developers, you'll get more bang for your buck by making executable documentation first - tests, deployment automation, build automation. Make it so that to do 1 logical action then there's only 1 step needed. How do i build this? Run the build command. How do i test this? Run the test command. How do i run only the unit tests? Run the unit test command. How do i start this locally? Run the…

GitHub have a pattern for this called "scripts to rule them all" - https://github.com/github/scripts-to-rule-them-all - I've not fully adopted it yet but I probably should, it looks very well thought-out.

Re: The case for continuous documentation

#47

Post by wmiel » Sun, Jun 06, 2021, 8:31 PM UTC

tanaypingalkar wrote: post #45

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…

Is there any lib/way that automatically generate doc for api/endpoint. I think it is possible to create such generator for graphql api.

You can checkout Swagger and OpenAPI, there are libraries to annotate the endpoints in the code and then generate interactive docs out of that.

Re: The case for continuous documentation

#48

Post by michael1999 » Sun, Jun 06, 2021, 8:47 PM UTC

yosefk wrote: post #3

If you essentially have one live version of your program, like you do when it runs on your servers, coupled documentation is probably a good idea. If you have multiple active versions, like you often do with software released to run on someone else's machines, coupled documentation "works," but has a big downside. Namely, it prompts people to "refactor mercilessly"/change everything all the time, together with the do…

I see the value in internalizing the cost of breaking changes. But rather than just suffer a doc burden to discourage change, why not fix it with something like Stripe’s version conversions?

Re: The case for continuous documentation

#49

Post by systematical » Sun, Jun 06, 2021, 9:03 PM UTC

ycombiswimm wrote: post #17

I completely agree that documentation should be part of the CI/CD and that it should be part of the code.

The only way for documentation to be part of CI (IMO) is for missing documentation to cause failed builds. There are a few ways I could think of to enforce this but is there anything off the shelf that does this?

Re: The case for continuous documentation

#50

Post by cryptica » Sun, Jun 06, 2021, 9:14 PM UTC

iib wrote: post #36

cryptica wrote: post #33

Earlier quoted context omitted.

I think this argument makes perfect sense. Personally I don't like in-line documentation. It's mostly popular among people who depend on bulky proprietary IDEs. I hate all these approaches which try to trick people into using proprietary tech. I enjoy reading a nice documentation website maintained by the open source organization; it also gives me a touch-point with the organization which created the library. I also…

Can you not just not write the documentation, even if it resides in the same repository, and then later make a commit to update it, as a separate task?

Yes, but why take up space in the actual source code and repo? It increases space usage both in terms of disk space (which means more download time) for the library and requires more scrolling when reading the code.

Also, if the library is a sub-dependency which the developer doesn't interact with directly, why should they download the documentation for it? They will never read those comments in the code anyway.