3 ms·

We're experimenting with putting our documentation in our monorepo (written in markdown, compiled and published to GDrive, Confluence, if god-help-you you're se

by gen220 6y ago

We're experimenting with putting our documentation in our monorepo (written in markdown, compiled and published to GDrive, Confluence, if god-help-you you're searching on one of those platforms). Nitty-gritty api documentation lives in the service's protobuf file, but "evergreen" architecture overviews and technical designs live in the repo. benefits: versioning, code review of docs, portability, plaintext search tools, docs show up while grepping for code, can change code and docs in same commit, git blame, you can "guess" where documentation for a service lives if you know it's location in the repo. downsides: not everyone enjoys learning markdown syntax, it's a skill orthogonal to communication. eng is a gatekeeper for changes to documentation, i.e. product can't go through it and fix typos. our code review tool does not have as good inline comment-discussion UX as G Docs (biggest one).

simonw 6y ago
I love keeping documentation in the same repo as the code, because you can enforce updates to the relevant documentation as part of the code review process. "This change is great - don't forget to update the docs in docs/blah.md before you land this pull request." You can even write unit tests that verify that certain things are mentioned in the documentation: https://simonwillison.net/2018/Jul/28/documentation-unit-tests/ https://simonwillison.net/2018/Jul/28/documentation-unit-tes...
- gen220 6y ago
  Ooh thank you, unittesting the documentation is a great tip that I will steal. Totally agree, code review is a huge plus for many reasons. If your company/project has a build graph (bazel, pants etc), you can even make the source file a dependency of the document, so whenever the source file changes, it's trivial to generate an automated "hey don't forget to update <doc> if it's relevant to this change".
andreareina 6y ago
Are you copy/pasting the md input into Confluence, the formatted html output, or doing something else?
- gen220 6y ago
  We use pants as our build tool, and somebody has graciously contributed a plugin for pants that generates confluence pages: https://github.com/pantsbuild/pants/blob/master/contrib/confluence/src/python/pants/contrib/confluence https://github.com/pantsbuild/pants/blob/master/contrib/conf.... Looks like a thin wrapper around the confluence API and a homebrewed md to html converter, that supports inter-document links. Looks like most of the code was written by folks at Twitter. Personally, I'd advocate for using pandoc (https://pandoc.org/ https://pandoc.org/) unless a custom solution like this makes sense and you have the eng resources to maintain/support it. Pandoc will give you a pretty sensible html document by default, and with some fine-tuning you can make the outputs look pretty great. Pandoc also generates beautiful and customizable latex-powered pdfs. We have a policy of publishing those to G Drive every minor version.

by gen220 6y ago

simonw 6y ago

I love keeping documentation in the same repo as the code, because you can enforce updates to the relevant documentation as part of the code review process. "This change is great - don't forget to update the docs in docs/blah.md before you land this pull request." You can even write unit tests that verify that certain things are mentioned in the documentation: https://simonwillison.net/2018/Jul/28/documentation-unit-tests/ https://simonwillison.net/2018/Jul/28/documentation-unit-tes...

gen220 6y ago
Ooh thank you, unittesting the documentation is a great tip that I will steal. Totally agree, code review is a huge plus for many reasons. If your company/project has a build graph (bazel, pants etc), you can even make the source file a dependency of the document, so whenever the source file changes, it's trivial to generate an automated "hey don't forget to update <doc> if it's relevant to this change".

andreareina 6y ago

Are you copy/pasting the md input into Confluence, the formatted html output, or doing something else?

gen220 6y ago
We use pants as our build tool, and somebody has graciously contributed a plugin for pants that generates confluence pages: https://github.com/pantsbuild/pants/blob/master/contrib/confluence/src/python/pants/contrib/confluence https://github.com/pantsbuild/pants/blob/master/contrib/conf.... Looks like a thin wrapper around the confluence API and a homebrewed md to html converter, that supports inter-document links. Looks like most of the code was written by folks at Twitter. Personally, I'd advocate for using pandoc (https://pandoc.org/ https://pandoc.org/) unless a custom solution like this makes sense and you have the eng resources to maintain/support it. Pandoc will give you a pretty sensible html document by default, and with some fine-tuning you can make the outputs look pretty great. Pandoc also generates beautiful and customizable latex-powered pdfs. We have a policy of publishing those to G Drive every minor version.