d4l-data4life/style-guide

Technical Writer style guide repo

About the technical writing style guide

The technical writing style guide provides guidelines for writing technical documentation and user assistance content at Data4Life.

Though the technical writing style guide is intended for technical writers, it also includes general rules and best practices for writing in English. We encourage anybody who'd like to make use of the style guide to do so.

We made every effort to ensure that the style guide fulfills its intended use, but we welcome your feedback and will consider it in future updates.

Should you have any comments, get in touch at [email protected].

Top tips from the style guide

1. Use American English.
2. Use the simple present tense.
3. Use the active voice.
4. Use contractions.
5. Use the serial (Oxford) comma.
6. Use common words and short sentences.
7. Directly address your users.
   • For example, Click here not You can click here.
8. Use sentence-style capitalization in headings.
   • For example, Data4Life wins award not Data4Life Wins Award.
9. Prioritize nouns, not pronouns.
   • For example, the password not it.
10. Avoid writing the following:
    • Please
    • Via
    • Suffers from
    • Comprises
    • Utilizes
    • Irregardless

style-guide's Issues

Column width is broken in GitHub view

I have tried many fixes for the column/table width in GitHub, which aren't all uniform and should be full-width. These columns are full-width in the asciidoc preview. I presume there will be some html/css related fix somewhere.

The following syntax works as an alternative to the current column formatting we use to make a CSV table.

,===
Document version,Revision date,Change description

0.8,January 2020,Initially created
,===

So far, I haven't managed to utilize this however.

Attributes errors

:font: and :toc: don't appear in this view. I don't know why.

Maybe it's because the GitHub repo view doesn't support this kind of content (it's not like asciidoc-preview in Atom). But then I need to find an alternative, because it is important to see a table of contents and icons in this document.

I need to find out why it doesn't work, and if I can fix it.