Hello Everybody. A quick question regarding documentation and docs in general. The sheer amount of docs that 1. exist 2. are important 3. get updated and 4. are interconnected is ridiculous, to say the least.
How do y’all keep up with all of these? Specifically, how do you manage to find the right doc and know which docs you need to read together and knowing which of those docs are out of date/most up-to-date?
4 Likes
Almost started a rant about doc writing in general but let me try to answer the question that was asked 
In terms of writing good docs I really like adding a lot of crosslinks with descriptions - kinda how you would when writing a blog.
Findability as I see it comes down to finding the right structure for the company or just a great search algo. I also really like making user specific table’s of content. You can’t rewrite everything to fit everyone’s point of view, but what is of interest to different people varies a lot and therefore an idea could be to group topics from different perspectives.
4 Likes
So, I’ve only seen one model where “documentation” is up to date, comprehensive, and useful: where you have a person (or a team!) whose sole job is maintaining documentation that is up to date, comprehensive, and useful 
So I think you’re looking at second best, which means you need to think through what is the one thing you’re optimizing for? What problem are you trying to solve?
Is it important that documentation be complete? Then make sure it’s baked into the process of building your product (e.g., generated from/with your engineering process).
Is it important that it be accessible? Limit the set of things that are documented and bake it into your schedule/cadence/calendar.
Small story: Back in grad school my fellowship sponsor ran a research center for Knowledge Management (this was the Aughts and KM was a thing). He had me speak to probably a dozen sponsoring companies about their efforts. Big companies investing in Sharepoint and wikis and librarians and all the KM detritus of the early 2000s. Only one organization seemed to do a good job. They had a big, single, organization-wide email list where people could ask questions. But all past emails were searchable so if you have a question about abltative performance in low temperature environments (lots of defense research) you’d do a quick search, find the person who answered a similar question last, and walk over to their desk. Does it scale? They had over 5,000 people in their main office. And now we have Slack, which is pretty close!
4 Likes
What would a new engineer want to read about as a part of their onboarding? What about a PM? A designer? A digital marketer?
3 Likes
If I were to boil the two thoughts so far - it comes down to the effective centralization and organization of documentation + some reliable/bought-in process to access that central “brain”
Is that fair?
2 Likes
Bottom line: this is really hard. But it’s worthwhile. You just have to develop an automatic reflex anytime someone mentions some kind of tribal knowledge or useful tidbit where you ask “can you document that?”
The other problem is getting everyone to use the same thing. I’m a fan of wiki-style products like Confluence or Notion for documentation so everyone can see it. If there are Google docs floating around in various employees’ drives, you have no visibility.
I also think you can curate lists of documents. Especially for onboarding new employees. What are the first things they should read upon joining the company?
2 Likes
Hey everyone! Wanted to surface a super helpful tool my team uses to speed up process documentation (both for formally documenting our product and informally sharing teammates how to do stuff).It’s called Scribe - basically you turn the recorder on, walk through your process, and it automatically generates a how-to guide with screenshots, texts, and keystrokes. It’s an unreal time saver.
1 Like
There’s a similar thread on reddit. very interesting answers. Here’s the link, take a look…
This topic was automatically closed 180 days after the last reply. New replies are no longer allowed.