New-comers generally find it hard when it comes to documentation. Keeping in mind this ambiguity, Google has published a documentation style guide for the developers. Moving forward, this will assist the budding developers to present better documentation.
It is pertinent to state that Google has launched precisely the same documentation style guide which it uses within the organization for writing the documentation of its own projects like Kubernetes and Dart.
Also Read: Google designs new algorithm to remove watermarks
What does the guide include?
Google has offered pretty much everything in the guide. One would be able to discover all from a word list to make sure the spelling of industry jargon (for instance: it’s not datacenter; rather it’s data center) is consistent. Moreover, the guide also contains the usage of hyphens (when and when not to use them). In addition, it also guides the users to put more emphasis on using active voice, in addition to educating about some other basic features of sound documentation.
One of the added features in the guide which may excite the developers is that it also talks about writing good API code comments. Furthermore, it also explains about how to best document command-line syntax.
The style guides of some of the big companies including Atlassian, Salesforce and WordPress are public. However, only a handful of them are as good and detailed as Google’s documentation style guide; particularly when we talk about the basics.
Quick Read: Google fires the writer of anti-diverse memo
TechCrunch reported that the team behind the style guide has stated that this document will continue to evolve over a period of time.
Things to avoid during documentation
- Being too cutesy
- Current pop-culture references
- Jerky or lengthy sentences
- Making fun of customers, competitors or anyone else
- Placeholder phrases like ‘please note’ and ‘at this time’
- Starting all the sentences with same phrase like ‘to do’ and ‘you can’
- Slogans or technical jargon
Leave a Reply
This site uses Akismet to reduce spam. Learn how your comment data is processed.
