Ask HN: How do you keep your technical docs in sync with code? • Hacker News Board

Re: Ask HN: How do you keep your technical docs in sync with code?

#11

Post by ardalanpouya » Mon, Sep 18, 2023, 10:26 AM UTC

hitchstory wrote: post #6

With annotated, declarative step-based YAML integration tests. They autogenerate how-to markdown documents via a jinja2 template: https://github.com/hitchdev/hitchstory (there are a few toy examples listed there) Depending on the app the docs might also embed artefacts generated under test - e.g. screenshots from playwright.

This is a very interesting idea. but I foresee two challenges here: (1) it sounds like alot of maitnance to keep a set of annotated tests that updates docs. (2) this does not sound like a solution for a company which produces handful of system behavior explaining docs on a daily basis. it looks like it is more so intended with low level documentation

Re: Ask HN: How do you keep your technical docs in sync with code?

#12

Post by ardalanpouya » Mon, Sep 18, 2023, 10:35 AM UTC

Double_a_92 wrote: post #5

We don't. Everything that is not part of the code will just get out of date. It's just best to reduce external documentation, or at least bundle all in one place. What works best is just creating a rough sketch of the idea, and store it somewhere next to the code with a datestamp. So it's clear that it's out of date, but if you really need some hint of how it was intended to work you can still look at it. (That is us…

I like the idea of timestamping docs. How often do you run into something being "annoyingly out of date"? Asking because it happens alot for us with onboarding docs specially. I am trying to find out what we are doing wrong

Re: Ask HN: How do you keep your technical docs in sync with code?

#13

Post by hitchstory » Mon, Sep 18, 2023, 10:45 AM UTC

ardalanpouya wrote: post #11

hitchstory wrote: post #6

With annotated, declarative step-based YAML integration tests. They autogenerate how-to markdown documents via a jinja2 template: https://github.com/hitchdev/hitchstory (there are a few toy examples listed there) Depending on the app the docs might also embed artefacts generated under test - e.g. screenshots from playwright.

This is a very interesting idea. but I foresee two challenges here: (1) it sounds like alot of maitnance to keep a set of annotated tests that updates docs. (2) this does not sound like a solution for a company which produces handful of system behavior explaining docs on a daily basis. it looks like it is more so intended with low level documentation

The integration tests require maintenance like all tests do. The doc compilation step doesnt require much maintenance.

There are examples there to demonstrate use on any level - e.g. to create unit-test level tests for a library or that generate code docs for programmers or playwright e2e tests that generate user-readable how to docs.

The interaction code requires maintenance but a lot of it very boilerplate. E.g. you need a function to interpret the "click" step to do the proper playwright click or drag-drop but it should function more or less the same for everybody.

Re: Ask HN: How do you keep your technical docs in sync with code?

#14

Post by ardalanpouya » Mon, Sep 18, 2023, 10:56 AM UTC

hitchstory wrote: post #13

ardalanpouya wrote: post #11

Earlier quoted context omitted.

This is a very interesting idea. but I foresee two challenges here: (1) it sounds like alot of maitnance to keep a set of annotated tests that updates docs. (2) this does not sound like a solution for a company which produces handful of system behavior explaining docs on a daily basis. it looks like it is more so intended with low level documentation

The integration tests require maintenance like all tests do. The doc compilation step doesnt require much maintenance. There are examples there to demonstrate use on any level - e.g. to create unit-test level tests for a library or that generate code docs for programmers or playwright e2e tests that generate user-readable how to docs. The interaction code requires maintenance but a lot of it very boilerplate. E.g. yo…

Gotcha! will take a deeper look. thanks :)