Blogs

Brief review of internal developer documentation style guide

September 22, 2017
Posted by: Rahul Karn
Category: Technical writing

Developer documentation Style Guide

In this blog post is for technical writers involved in writing internal developer documentations. In this, you will learn brief comparison of different style guides (Google, Atlassian, and SalesForce).

Style guide for technical writing It’s the first thing a newcomer needs to study to understand and track the changes in a project. A bad documentation is worse than no documentation at all.

Many companies have their own internal developer documentation style guide to write documentation error-free and absolutely clear to prevent any kind of ambiguity but, when they come across external contributors it becomes tough to understand and change the style guide into its own format.

Google is releasing its internal developer documentation style guide. This can quite literally guide your documentation, giving you a great starting point and keeping things consistent.

If you want to follow Google’s style guide for your project, you can simply access it here.

In order to better support external contributors to open source projects such as Kubernets, Amp, or Dart, recently Google has released its own internal documentation style guide.

The documentation style guide of Google can be useful for general issues like reminders to use second person, present tense, active voice, and the serial comma. They have also listed a few things to avoid while documentation.

Being too cutesy
. Placeholder phrases like ‘please note’
. Choppy or long-winded sentences
. Starting all sentences with the same phrase
. Current pop-culture references
. Jokes at the expense of customers, competitors or anyone else.
.

Few more such as Atlassian, WordPress, and Salesforce also released their internal style guide to optimize consistency across developer documentation.

A glimpse of highlights of these style guides is given here to make documentation an easy and accessible task for the newcomers and external contributors.

Style guide for Atlassian developer documentation

· Ensure a DOCS: maximum image width of 700 pixels.

· Use the DOCS: theme colors for sophisticated effects.

· Include the DOCS: product version to which your update is relevant. Use ‘Available‘, ‘Changed‘ and ‘Deprecated‘.

· Use plenty of DOCS: code samples.

· Make use of our DOCS: templates.

· Mark all drafts clearly as DOCS: work in progress.

· Do not DOCS: delete, move or rename any page that you did not create yourself.

· Use DOCS: internal link format rather than the full [http://xxxx] external link format.

· Be aware that the content of some pages is DOCS: reused in other pages. Make sure you put your content in the right place. This applies in particular to the Atlassian Plugin Framework documentation.

· Maintain a DOCS: consistent style, layout, grammar and format with the rest of the page or space.

· Use Australian DOCS: spelling. For example, use ‘organisation’ not ~~organization~~. Use ‘customising’ not ~~customizing~~.

· Use title case for DOCS: headings, not sentence case. For example, ‘This is a Heading’.

For complete guide visit https://developer.atlassian.com/about/style-guide-for-the-atlassian-developer-documentation

Few points from WordPress documentation style guide:

1. Include screenshots

2. Theme name and menu items are italicized

3. Use title case for section titles

4. Spell out numbers nine and under

5. Use US spelling and punctuation conventions

6. Refer to the dashboard, not the admin area

7. Don’t number your section heading

8. For complete guide visit https://developer.wordpress.com/themes/documentation-style-guide/

Salesforce’s guide has the following sections:

· Styles A-Z–Alphabetical reference of basic guidelines for grammar and usage for documentation and user interface text.

· Glossary–Definitions and usage of Salesforce terms and other key user interface terms.

For complete guide visit https://developer.salesforce.com/docs/atlas.en-us.salesforce_pubs_style_guide.meta/salesforce_pubs_style_guide/overview.htm

Blogs

Brief review of internal developer documentation style guide

Developer documentation Style Guide

Leave a Reply Cancel reply