Malte Ubl

Re: https://www.industrialempathy.com/posts/design-docs-at-google

> ... sketching out that API is usually a good idea. In most cases, however, one should withstand the temptation to copy-paste formal interface or data definitions into the doc as these are often verbose, contain unnecessary detail and quickly get out of date.

Using R Markdown (or any Turing Complete documentation system), it's possible to introduce demarcations that allow the source code snippets to be the literal source of truth:

// DOCGEN-BEGIN:API_CLASS_NAME /** * <description> * * @param arg <description> * @return <description> */ uint8_t method( type arg ); // DOCGEN-ENDED:API_CLASS_NAME Use a GPT to implement a parser for snippets in a few minutes. Then invoke the function from the living document for given a source file, such as:

`r# snippets -> parse.snippets( "relative/path/to/ClassName.hpp" ); docs -> parse.api( snippets[[ "API_CLASS_NAME" ]] ); export.api( docs ); ` The documentation now cannot ever go stale with respect to the source code. If the comments are too verbose, simplify and capture implementation details elsewhere (e.g., as inline comments).

In one system I helped develop, we were asked to document what messages of a standard protocol were supported. The only place this knowledge exists is in a map in the code base. So instead of copy/pasting that knowledge, we have:

MessageMap MESSAGE_MAP = { //…

> it doesn't matter if you have a blog article recommending structured emails over video calls

Exactly! Funny thing is that if you send these people an article explaining the benefits of written docs (design docs, RFCs, proposals, any text document documenting a decision), they will just simply not read it.

I'm on a team where I believe we started gigantic refactoring and redesigning projects without being clear on the goals, non-goals, and tradeoffs we take. I proposed that before we start working on something huge, we should write a short document where we explain what, how and why we want to do.

I recommended them some articles, for example "Design Docs at Google" [1], and "Scaling Engineering Teams via RFCs: Writing Things Down" by Gergely Orosz [2], but I couldn't even convince them to read those articles...

I didn't even send them my favorite posts about the Amazon 6-page memo, because I knew they'd dismiss the whole idea in a second (no matter if I told them that we could do "OurCompany 1-page memo").

This lead me to the sad realization, that our team will never start "writing things down". In my opinion, it would force us to think things through, but it seems like they disagree, or they just don't care.

My coworkers will not even read a 3-paragraph ticket, but they'd love to talk about the same ticket for an hour in a video call. Then in 3 weeks, nobody remembers anything anyway, and they discuss it again.

[1]…

I used the following sources to create an RFC template (and promote the document culture across the engineering documentation):

- https://www.industrialempathy.com/posts/design-docs-at-google/

- https://github.com/rust-lang/rfcs

- https://github.com/kubernetes/enhancements/blob/master/keps/sig-architecture/0000-kep-process/README.md

- https://blog.pragmaticengineer.com/rfcs-and-design-docs/

Hint: tailor the process and template structure based on your org size/maturity and needs. Don’t try to blindly mimic/imitate.

Perhaps read the section dedicated to this point: https://www.industrialempathy.com/posts/design-docs-at-google/#cross-cutting-concerns

Some cross-cutting concerns are about more than just code, but things like "how will you monitor this for reliability?" or "this system reads user-sensitive data, how will those reads be audited?" and so on. Usually the answer is short: "use standard system xyz" - but having it there and ensuring it's followed through on are important.