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

Purpose	Guidelines
Clarity	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.
Comprehension	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

Purpose	Guidelines
No Cryptic words	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 breached. 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. Tip 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.
Ambiguity	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.