“Google Developer Documentation Style Guide” is a guide for Google developers on how to write the developer documentation. As someone who have been involved in technical documentation for years now, I find a general lack of such guides from other companies interesting and slightly disturbing.
Kudos to Google for the effort and for sharing with all of us who are trying to improve the technical writing.
Sara Rosso shares some thoughts on what to document and share, after publishing over a 1,000,000 words while working at Automattic. Here’s the gist of it:
- If you’re the go-to person for something in your company, consider how much of it is just gatekeeper information you could document properly to help someone else learn/grow from or work on independently.
- Separate out processes and historical background from your strategic expertise. Processes and backstory are not really ‘what you know.’ It’s much better to be a person someone asks ‘why’ or ‘when’ to do something vs. the logistics of a ‘how.’ How can and should be documented for others to build off of regardless of your involvement. This should free you up to be more involved in the why, the new, and the next of your work.
- If you’re repeating yourself in private chats or (gasp!) email on a specific topic, document it. That’s also what drove me to create this blog – being able to answer someone’s question with an answer you’ve already carefully crafted for someone else is a great feeling (and a great use of your time)!
- Will someone want to know why you decided or executed something a specific way later? Share as much background as possible so colleagues are brought up to speed immediately. Share the setup & thought process you went through, where to find more information, and even the facts, ideas, or information you considered but deemed outside of scope for the particular project. My goal is to hopefully never have someone ask “where did this come from?” or “what’s your source?” or “did you consider this?” (when I had) and instead focus on enriching the discussion or challenging my ideas vs. asking me for information I should have provided in the original post.
- Gather the best, most complete, or authoritative things you’ve authored and submit them as potential onboarding materials for new team members. Challenge them to ask questions and to find something you need to document.
- If important progress is made, be sure to update your documentation, or retire in favor of something newer or more complete. We do this by linking from old posts to new ones, and all it takes is a quick comment and a link on an old post.
GitHub blog is “Announcing Open Source Guides“:
we’re launching the Open Source Guides, a collection of resources for individuals, communities, and companies who want to learn how to run and contribute to open source.
Open Source Guides are a series of short, approachable guides to help you participate more effectively in open source, whether it’s:
- Finding users for your project
- Making your first contribution
- Managing large open source communities
- Improving the workflow of your project
These guides aim to reflect the voice of the community and their years of wisdom and practice. We’ve focused on the topics we’ve heard about most, and curated stories from open source contributors across the web.
I think it’s a great idea and I really like the execution too. Most of what I know about Open Source comes from years of participation, and from reading old books, manuals and licenses – not something that is easy to share with people who are just getting their feet wet.
GitHub’s Open Source Guides are very simple, concise and specific. And they cover a variety of subjects, not just the legal or technical side of things, but also communications, support, marketing, etc.
Suhas Chatekar explains how they use API maps to visualizing complex APIs, resources those API expose and how those resources relate to each other.
If only there was a tool that would help with this …
PagerDuty shares their Incident Response Documentation:
This documentation covers parts of the PagerDuty Incident Response process. It is a cut-down version of our internal documentation, used at PagerDuty for any major incidents, and to prepare new employees for on-call responsibilities. It provides information not only on preparing for an incident, but also what to do during and after. It is intended to be used by on-call practitioners and those involved in an operational incident response process (or those wishing to enact a formal incident response process).
I think this is a goldmine for anybody involved with incident response teams, operations, monitoring, technical support, network centers, and other similar setups. Not only it covers the specific steps and expectations during different situations, but it also defines the culture, which the company is trying to built.
I wish I had this 15 years ago when I was involved in setting up the Network Operations Center (NOC). I will definitely use it in the near future, when we’ll be setting up the support department at work.