Article Guidelines

Owned by Deepak K (Unlicensed)
Feb 11, 2020
3 min read

In this Guide, you will learn how to write an Article.

Before you start

  1. Understand:
    Understand the topic you’re writing about. Ask yourself: Who is going to read it? How is this article helpful for the reader? What useful information do they need to know?

  2. Prepare Index: Before committing to writing, structure / index your guide.

    1. How it works: List down the step by step actions involved in the activity. Add steps that are simple and self-contained. Try stick to 3-5 steps per activity to avoid overloading readers.

    2. Glossary: List down and Define the fundamentals / Glossary involved in the article.

Technical Writing Tips:

Example

Write it as

Correct Example

Example

Write it as

Correct Example

1

While suggesting to navigate:
E.g. Click on the tool bar

Make action as Italic. As mentioned here: Click must be in italic

Click on the tool bar

2

If you are suggesting user to direct to any field inside the system.

Mention “go into” and put the field “setting” as bold

go into setting

3

E.g.: From Dashboard, go into your Profile and further go into Settings

Instead of using long sentence, use short Navigation with specific start instruction such as “Lunch” supported by arrow icon “>”

Lauch Dashboard > Profile > Settings

4

If you are referring to any term in Fundamentals.

The fundamental or Glossary term used must be in Bold. This term will be linked to the Fundamentals Glossary List. If the term is unavailable in the fundamental glossary, it must be added.

APOB


Voice and Tone

  1. Guide: Think of yourself as a tour guide for our readers. Whether you’re leading them through our educational materials or a task in our app, communicate in a professional and helpful way.

  2. Educate: Tell readers what they need to know, not just what we want to say. Give them the exact information they need, along with opportunities to learn more. Remember that you’re the expert, and readers don’t have access to everything you know.

  3. Use active voice: Use active voice. Avoid passive voice. In active voice, the subject of the sentence does the action. In passive voice, the subject of the sentence has the action done to it.
    Right: We will receive your inventory.
    Wrong: Your inventory is being received.

  4. Be concise: Use short sentence (Optimum 5 to 7 words). Avoid long and complex statement. If required, break your sentences into smaller parts.

  5. Don't be informal: Be specific. Be professional. Avoid vague language. Use only the known terminology. Avoid use of any new terminologies, which does not exist in the building block or glossary list.

  6. Be consistent: Stick to the patterns and style points outlined in this guide and the template provided below.

  7. Avoid repetition: Do not use repetitive methods to describe one thing. E.g. If you are defining the meaning of a building block, define it in one exact sentence. Form second sentence only if you have any additional information to add.

  8. Maintain a tone: Use plain language. Don't be salesy and don't use complicated business jargons apart from defined in your glossary.

  9. Abbreviations and acronyms: Spell out abbreviations the first time you mention it. Then use the short version for all other references.
    First use: Network Operations Center (NOC)
    Second use: NOC

  10. Use a colon: Use colon (rather than an ellipsis, em dash, or comma) to offset a list.

    • E.g. Erin ordered 3 kinds of donuts: glazed, chocolate, and pumpkin.

  11. Capitalisation: Use Sentence Case. Don't capitalize random words in the middle of sentences.

  12. Use US English instead of UK english.

  13. Use specific and relevant examples only.

 

Do’s:

  1. Anything that is being done in settings is = configuring

  2. While taking screenshot hover over the relevant action and keep mouse on the icon

  3. Consignmnet builder = create consignment tool "+"

  4. Example should be mentioned as E.g. Receive Returns. Do no use Ex / Eg For Eg etc.

 

Don’ts:

  1. Words to avoid:
    deploy (unless you’re talking about the military or software)
    execute (use run or do)
    initiate (use start)
    commit or pledge (we need to be more specific — we’re either doing something or we’re not)
    collaborate (use working with)
    combating (use working against or fighting)
    countering (use answering or responding)
    disincentivize or incentivize
    empower
    facilitate (instead, say something specific about how you are helping)
    impact or impactful
    innovative (use words that describe the positive outcome of the innovation)
    in order to (use to)
    key (unless it unlocks something, use important or omit)
    modify (use change instead)
    streamline
    strengthening (unless you’re referring to bridges or other structures)
    tackling
    touchpoint (mention specific system components)
    utilize (use use)
    For Ex (Use E.g.)