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.
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).
You can even write unit tests that verify that certain things are mentioned in the documentation: https://simonwillison.net/2018/Jul/28/documentation-unit-tes...
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".
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/) 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.
can never find it again...
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-we...
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.
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.
Everything needs a default automatic TTL, just like renewable leases.