GenPipes Writing Style Guide

How do we make it really easy and simple for GenPipes users to adopt GenPipes?

The very basic ingredient is GenPipes itself. It needs to be flexible, scalable, intuitive, easy to deploy and quick to gather information insights. Besides that, one of the key enablers towards facilitating GenPipes onboarding is its user documentation that satisfies the following criteria:

  • Concise,

  • Current & Continuously updated,

  • Consistent,

  • Clear, and

  • Comprehensive

This Writing Style guide is inspired by Google Style Guide which is adopted by several open source projects out there. Besides that, there are other references such as API Documentation Guide, and Best REST API Template. These are in use by many projects and many engineers, who collaborate globally to create world class software and documentation, used across verticals and industries. As of writing this, GenPipes does not provide API interfaces yet. It only provides executable that can be invoked to run various genomic pipelines.

Goals and Audience

This guide is intended to help GenPipes technical writers to form a consistent approach for writing its documentation.

The primary goal of this guide is to codify and record decisions that Google’s Developer Relations group makes about style. The guide can help you avoid making decisions about the same issue over and over, can provide editorial assistance on structuring and writing your documentation, and can help you keep your documentation consistent with our other documentation.

How to use this Guide

This guide is a reference document. You can choose to read it linearly or look up specific issue or topic using the search box.

For issues not covered in this guide, see Google Style Guide or Other Style Guides.

Restructured Text Style Guide

You may also want to refer to some of the ‘coding’ standards applied to documentation files developed using Sphinx automation engine and Restructured Text formal. See Sphinx Documentation Style Guide for details.

Documentation Do’s




Most of the principles that apply to good technical documentation also apply to accessible technical documentation:

  • Use correct grammar and punctuation.

  • Use active voice and present tense.

  • Write clear, simple sentences.

  • Be consistent.


Include screenshots! Users find screenshots very helpful, particularly annotated screenshots. When using screenshots as figures, remember to circle the relevant buttons, add arrows pointing out mentioned links, or highlight key sections.

Common norms

Spell out numbers nine and under. Use numerals for 10 and up.

Common norms

Use comma before “and” in a list of several items. For example: “This theme is elegant, simple, and easy to use.”

Shared doc development norm

Do not delete, move or rename any document, page or topic which you do not own or did not create. Discuss and review as there may be cascading impact and changes required to be done for the same. Collaborate on such wide impact documentation changes.

Cross referencing common norm

Be aware that the content of some pages is included in other pages. Make sure you put your content in the right place, if it is cross referenced multiple times and also across guides. Follow similar principles just as in source code common files and function norms. This applies in particular to the Concepts and Usage Guide, FAQ, SDK API documentation.

Document Consistency

If you are inserting a topic in an already existing piece of content, say a page or in a new section, ensure that you follow a consistent style, layout, grammar and format with the rest of the page.

Documentation Do not’s



No Cryptic


Avoid the use of Buzzwords. When you use any acronym, expand it for first time use, with acronym in brackets. For subsequent use, acronym is fine.

Not recommended: Use JBMgmtSvc to schedule this task if this policy is

Recommeded: Use Job Management Service (JBMgmtSvc) to schedule this task
if privacy policy is breached. Refer to JBMgmtSvc details here (refer to link)
on how to set up job management schedule

No Complicated Language

No long sentences. Think of the twitter 140 characters generation. Avoid choppy sentences.


Think of your audience

Compare the first paragraph below to the second in terms of complexity.
  • When you write, imagine you speaking these very same words as if you were saying these to someone in a conference call or Webinar where no real real time clarification or feedback is possible by those who’d read it and try to understand what you wrote at a later point in time.

  • When you write, imagine your audience reading what you write, at a later point in time. Face to face conversation allow the luxury of real-time clarifications, additional cues via facial expressions and tone. Written word is more powerful and could be confusing as it lacks that luxury.

Avoid Repetition

Use of repetitive phrases such as ‘To do’, or ‘Here is’, or “You can” at the start of each sentence is detrimental to reader attention.

Enterprise Focus

Avoid current pop-culture references.

Appropriate Language

No Jokes at the expense of customers, competitors or anyone else for that matter.

Spoiler Alert

Avoid trying to document or talk about future features or solutions or products or enhancements, even in innocuous ways.


Avoid the modal verbs such as could, may, might, and should in technical documentation. Modal verbs are ambiguous and leave the reader wondering what to do. For details, visit Modal Style Guide.