3 ms·

Another related challenge: encouraging a culture of there being a predictable and searchable place documents live, so when someone has written a document you ca

Another related challenge: encouraging a culture of there being a predictable and searchable place documents live, so when someone has written a document you can actually find it.

larrik 6y ago
I'll put it in Confluence! can never find it again...
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.
simonw 6y ago
Two approaches I've used for that: 1. Having a "doc of docs" for each team - a document (Google Doc, wiki page, whatever) that acts as an index for all of the other documentation. If anyone asks "where's the documentation for X?" the answer should be "It's in the doc-of-docs. And if it isn't, it's your job to find it and put a link to it in the doc-of-docs". 2. Get a good search engine! I built a search engine for work that indexed documentation content from 8 different sources, because building a single search index was easier than convincing dozens of teams to switch the documentation solution they were using. I used an improved variant of the technique I described in https://24ways.org/2018/fast-autocomplete-search-for-your-website/ https://24ways.org/2018/fast-autocomplete-search-for-your-we...
- specialist 6y ago
  Maybe also add basic metrics. Like number of views, popularity over time, sparklines for edit activity, ... Maybe even some social features, with a decay rate. So teammates recently tagging things as "helpful!" could nudge me to pay attention. Any additional signal to help noobs like me while foraging.
  - SamuelAdams 6y ago
    At that rate you're better off buying some software that handles all this for you. Enter Microsoft Sharepoint. Yikes.
  - simonw 6y ago
    An idea I had but never really executed on was a mechanism for tagging documentation as "should be reviewed at least once every X months" - for things like setting up developer environments. That way a team could be alerted if their documentation was due-for-review. One person gets assigned a task to review it. They look through it, update it if necessary, and either way put a "last reviewed by X on date Y" tag on it so people who read it can tell that it's still relevant.
- yolo42 6y ago
  I've adopted the doc of docs method and it has made my life incredibly easy! I was in a position where I'm a bottleneck of information because no one else in the company new about the product other than me. I wrote a ton of documentation for employees and users but I still was spending upwards of 20 hours every week just answering questions. I built the doc of docs in 2 hours and that has helped significantly. Combine this with always replying with a link instead of a dedicated explanation has been extremely fruitful!
specialist 6y ago
FWIW, my last team had too much documentation. It's just so hard to cull stale info. I really struggled to discern what I could ignore. Everything needs a default automatic TTL, just like renewable leases.

Another related challenge: encouraging a culture of there being a predictable and searchable place documents live, so when someone has written a document you can actually find it.

larrik 6y ago

I'll put it in Confluence! can never find it again...

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.

simonw 6y ago

Two approaches I've used for that: 1. Having a "doc of docs" for each team - a document (Google Doc, wiki page, whatever) that acts as an index for all of the other documentation. If anyone asks "where's the documentation for X?" the answer should be "It's in the doc-of-docs. And if it isn't, it's your job to find it and put a link to it in the doc-of-docs". 2. Get a good search engine! I built a search engine for work that indexed documentation content from 8 different sources, because building a single search index was easier than convincing dozens of teams to switch the documentation solution they were using. I used an improved variant of the technique I described in https://24ways.org/2018/fast-autocomplete-search-for-your-website/ https://24ways.org/2018/fast-autocomplete-search-for-your-we...

specialist 6y ago
Maybe also add basic metrics. Like number of views, popularity over time, sparklines for edit activity, ... Maybe even some social features, with a decay rate. So teammates recently tagging things as "helpful!" could nudge me to pay attention. Any additional signal to help noobs like me while foraging.
- SamuelAdams 6y ago
  At that rate you're better off buying some software that handles all this for you. Enter Microsoft Sharepoint. Yikes.
- simonw 6y ago
  An idea I had but never really executed on was a mechanism for tagging documentation as "should be reviewed at least once every X months" - for things like setting up developer environments. That way a team could be alerted if their documentation was due-for-review. One person gets assigned a task to review it. They look through it, update it if necessary, and either way put a "last reviewed by X on date Y" tag on it so people who read it can tell that it's still relevant.
yolo42 6y ago
I've adopted the doc of docs method and it has made my life incredibly easy! I was in a position where I'm a bottleneck of information because no one else in the company new about the product other than me. I wrote a ton of documentation for employees and users but I still was spending upwards of 20 hours every week just answering questions. I built the doc of docs in 2 hours and that has helped significantly. Combine this with always replying with a link instead of a dedicated explanation has been extremely fruitful!

specialist 6y ago

FWIW, my last team had too much documentation. It's just so hard to cull stale info. I really struggled to discern what I could ignore. Everything needs a default automatic TTL, just like renewable leases.