“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.
WordPress Theme Developer Handbook:
The Theme Developer Handbook is a repository for all things WordPress themes. Whether you’re new to WordPress themes, or you’re an experienced theme developer, you should be able to find the answer to many of your theme-related questions right here.
Finally, there is a more organized resources that WordPress Codex!
I came across a very handy tool for writing quick and simple documentation – Documenter v2.
It provides a quick and simple web interface to handle document meta information (titles, subtitles, author, created and updated dates, etc), sections, styles, extra buttons, and more. You can also download and save the results, as well as continue where you left off later.
More and more paper work is moving into the digital domain, including legal documents. I’ve previously linked to Docracy – a service that provides a collection of legal documents, as well as tools to negotiate and sign them. Today I was made aware of another service – FormSwift. Some might find it to be more comprehensive, up-to-date and user friendly than the alternatives.
Have a look at the FormSwift’s collection of the free legal forms, which cover such categories as business, family, financial, life planning, real estate and other. Their tools are pretty sweet too, with support for Word and PDF files, and an online editor for PDF – not something you see every day.
I’ve mentioned Graphviz many a time on this blog. It’s simple to use, yet very powerful. The dot language is something that can be jotted down by hand in the simplest of all text editors, or generated programmatically.
The official website features a gallery, which demonstrates a wide range of graphs. But I still wanted to blog a few examples from my recent use.
Continue reading “Using Graphviz dot for ERDs, network diagrams and more”
It’s after bits like this one, I think I should spend more time reading documentation:
Create a new transaction.
This routine should _never_ be called by anything other than RT::Ticket. It should not be called from client code. Ever. Not ever. If you do this, we will hunt you down and break your kneecaps. Then the unpleasant stuff will start.
TODO: Document what gets passed to this
RT::Transaction->Create() developer manual for Request Tracker 4.2.