2 min read
Coders are often assumed to be introverts who love programming, coffee, other geeky stuff and not much else. If you’re a non-technical person who has ever had to work with a developer you’ll know how much they hate documentation. It’s just not in their DNA. However, the fact remains that it is essential that developers know how to document well, along with being able to write clean code. Earlier this week, Google has released to the public its own Developer Documentation Style Guide, to help them write better documentation.
For a project, particularly those that are open source, it is imperative that their documentation is easily understandable in order to get maximum contribution from third-party sources. For years, Google’s technical writers have been documenting following in-house rules. But since Google has numerous open sourced projects of its own, like the commonly used Accelerated Mobile Pages (AMP), they have made their style guide open for everyone to view.
The guide will ensure correct spellings, correct grammar, and the right usage of punctuation. It also suggests that people avoid using technical jargon but the content should not seem informal. There should be no repetition of phrases, pop culture references, or jokes.
The guide is very easy to understand but is by no means an industry standard that Google is thrusting upon people. In order to help people to grasp it easily, Google stated in the official blog post:
“The style guide is a reference document, so instead of reading through it in linear order, you can use it to look things up as needed. For matters of punctuation, grammar, and formatting, you can do a search-in-page to find items like “Commas,” “Lists,” and “Link text” in the left nav. For specific terms and phrases, you can look at the word list.”
There are other developer documentation guides available on the Internet as well. It’s all about what is better suited for you but it is recommended that, if you’re a developer, you adopt one so that you can document well.
