Skip to content

Latest commit

 

History

History
92 lines (51 loc) · 3.74 KB

docs-contributing-guidelines.md

File metadata and controls

92 lines (51 loc) · 3.74 KB
Raw

Docs Contributing Guidelines

  1. Before you start
  2. Rules
  3. Language
  4. Formatting

Before you start

When working on your docs, answer the 3W questions:

  • Why do you need to write it?
  • Who is your target audience?
  • What do you want to say?

For example:

I need to write this document (why) because I have created this API. I have to notify (who) the developers about (what) new endpoints, callbacks and methods.

This will help you focus on what you actually need to say, structure the text and keep the requirements of your target audience in mind.

If you struggle to start with a new documentation, see the basic markdown template.

Rules

  1. Follow the suggested template and publication flow.

  2. Go from the most important piece to the least important.

  3. For every method or callback provide an example.

  4. Always provide a use case or at least a context.

  5. Keep it simple and be concise – say what you need to say. No more, no less.

Language

  1. Use the standard United States (U.S.) English throughout the docs. When in doubt, consult Merriam-Webster dictionary.

  2. Don’t assume that English is the first language of your reader. Write clearly and straightforwardly.

  3. Avoid colloquial expressions and jargon.

  4. Don’t make your sentences too long.

  5. Use the active voice whenever possible.

  6. Use the present simple tense whenever possible.

  7. Keep the terminology consistent throughout the document.

  8. Address the reader in the second person (“you”), and use the possessive “your”. Don't use vague subjects like one, somebody, etc.

  9. For a hypothetical person (e.g. “a user”), use gender-neutral pronouns (they/their/them):

    • he or she = they
    • him or her = them
    • his or her = their
    • his or hers = theirs
    • himself or herself = themselves

Formatting

  1. Keep the fonts, indentations, spacing, etc. consistent.

  2. Headings must clearly describe topic or purpose. Don't capitalize the titles.

  3. Use a bulleted list for options, and a numbered list for steps. Create a list when you name three or more elements.

  4. Don’t obscure the links:

Writing hints

  1. Think of your project as a tool created to solve a particular problem.

  2. The docs are there to answer questions. Every documentation should follow the basic structure of answers, from the most fundamental to the most advanced ones.

  3. Remember that developers usually seek answers and solutions. If they need to decide where to seek them, they are slowed down. Keep your documentation organized from the most important information to the least important one. If it's a complex project, organize the sections from the most basic to the advanced ones.

  4. If you got stuck at describing a third method in a row, don't fight to be original. Sometimes it's better to repeat yourself than not to say nothing at all. Remember that developers usually skim through the docs instead of reading them line-by-line.

  5. When providing a code snippet, use example values, variable names or inline comments to draw an additional background to your example or use case.

  6. Try to predict questions the reader may ask and answer them along the text.

  7. Assume that the reader has zero knowledge and infinite intelligence.

  8. Imagine you're explaining what needs to be done to a fellow developer.