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:
|
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 |
---|---|
|
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
|
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. |