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.
Definitely. I do see a lot of value in understanding what different teams in my org are working on and am excited to read about it; I write in a manner that caters to that kind of audience, to present information in a no-frills, easy to consume manner so the readers don't feel like they've wasted any time.
A good culture of writing is very important to scale; as companies grow, the tail doesn't know what the head is doing. I won't harp on some imagined "waste" that can be saved by better communication; instead better communication simply makes everyone feel like they're on the same page and suggest/contribute to the org's growth. That itself is a big deal.
I suspect however I would put it in the category of 'I saw a tweet about the film of the book' for descending levels of nuance (but increasing levels of getting the point across)
I spent 40 hours making a 18 minute video. If that's run at 2x, that's a 9 minute video. So that's 266:1 ratio.
And I made the video because some people read and some people watch.
Again the video was well recieved, it was however probbably not worth the time. I only did it because I was remote with bad internet so it was how I could be successful at that time.
It would be an interesting experiment to visibly prepend the search queries each employee had done before asking a question to their actual question, in order to discourage asking questions before searching for the answer. You said you had built your own search solution, so clearly you could wire up a form that actually does this.
In orgs where the muscle for long-form reading has atrophied (for the above reasons), you can try to write document to account for a weak long-form-reading muscle.
Begin your document with an abstract TLDR and ToC, open each top-level section with a TLDR paragraph, and provide pointers that imply the TLDR assertions are supported by evidence (i.e. internal links to the relevant section).
The key to good TLDR-writing is terse, in-order parsable sentences, and short paragraphs (one sentence, maybe two per paragraph), with tasteful font-weight choices. I'd discourage using font-weight outside of TLDR's, except maybe to highlight keywords.
I think wikipedia is a glowing example of what documentation should be. Some pages are huge (e.g. https://en.wikipedia.org/wiki/World_War_II), but each section is dense, and filled with links to more detailed pages. To find the specific answer to some question, you often only need to navigate the table of contents and two or three sections/links. And yet, the pages can also be read straight-through. Writing like this is a hard skill to earn, but it's reward is probably a culture of reading.
As an American, I've never heard of this, and can't even imagine it.
Instead, using a written document absolutely forces the presenter/writer to have clarity in thought and it absolutely requires that they "cut the bullshit" and get to the point – what matters and what doesn't matter.
These kinds of meetings will derail if the writer hasn't fully fleshed out their ideas or even if the document is missing important structure ... the purpose of the document, what the author is trying to get out of the meeting ("what is the success criteria for the document or meeting?"), what's in scope, if it's a technical document then clarity in functional requirements, non-functional requirements/constraints, options/alternatives, trade offs, and so on.
In my honest opinion, the document driven meetings provide Amazon a competitive advantage.
Is it literally a quiet-read time where everyone just sits there silently reading a shared doc? Or is it what Ive seen happen in a lot of companies where someone projects the doc, and walks through it, reading/summarizing it aloud to attendees. I like to call that activity "executive storytime", since it's often underlings reading status reports to execs.
Some reasons why (loosely paraphrasing internal guidance on how to run meetings and why writing culture matters):
- PowerPoints are lazy/evil, and not good formats for conveying complex ideas; by nature, PPT's encourage shallow thinking, and is thus antithetical to the goal of having rigorous analysis/deep-thinking in making complex tech/business decisions
- Docs should stand on their own, without needing to be presented or walked-through by a person; forcing you to explain your ideas and support them in such a way that any sufficiently motivated reader can follow along and work out what they mean on their own, is again a way to encourage you to be rigorous and thorough (but limiting you to 6-pager format, for brevity)
- Writing long-form paragraphs and full sentences forces you to take time to refine your ideas
- Forcing people to take time to digest the doc first, gives everyone a chance to take notes and formulate ideas/responses to the info/arguments presented; this saves a lot of time as compared to, walking through a doc/slides for the first time, and having a roomful of people encounter those ideas for the first time and to ask questions in real time as they encounter them... reading the doc should hopefully already address the most common questions/critiques, and so you can spend more time on 2nd/3rd-order more advanced decisions or arguments
If you try talking during this time, you will get lots of dirty looks (and then probably be fired if you keep it up).
I've invested a great deal of effort in writing documents in the past only to realize that very few co-workers were taking the time to read what I'd written.
There are workarounds for this. The most famous I can think of is the Amazon culture where each meeting starts with 10 minutes of quiet reading, to ensure everyone is on the same page.
I imagine it's part of a writing culture though. Once people understand that an organization values writing, they'll take the time to read.