diff options
author | Kristian Aune <kkraune@users.noreply.github.com> | 2016-06-22 08:45:20 +0200 |
---|---|---|
committer | GitHub <noreply@github.com> | 2016-06-22 08:45:20 +0200 |
commit | 6f307b7924a72b38f3f2bf1e8f62a922d68df409 (patch) | |
tree | 2a349618d1b67b827df0738c51ca24f79ab7336f /README-documentation.md | |
parent | a9f1b6f1bc23efa52c0f09fea69aa94aa35bb06d (diff) |
more best practises
Diffstat (limited to 'README-documentation.md')
-rw-r--r-- | README-documentation.md | 6 |
1 files changed, 5 insertions, 1 deletions
diff --git a/README-documentation.md b/README-documentation.md index 81d5d93199e..01a95ba6ad4 100644 --- a/README-documentation.md +++ b/README-documentation.md @@ -62,6 +62,10 @@ Make the text as short, clear, and easy to read as possible: * Avoid superfluous words such as "very". * Avoid filler sentences intended to improve the flow of the text - documents are usually browsed, not read anyway. * Use consistent terminology even when it leads to repetition which would be bad in other kind of writing. +* Use active form "index the documents", not passive "indexing the documents" +* Avoid making it personal - do not use "we", "you", "our" +* Do not use &quot; , &mdash; and the likes - makes the document harder to edit, and no need to use it. +* Less is more - <em> and <strong> is sufficient formatting in most cases ### Links @@ -72,4 +76,4 @@ Example: <h2 id="my-nice-heading">My nice Heading</h2> If this algorithmic transformation is followed it is possible to link to this section using <a href="doc.html#my-nice-heading"> without having to consult the html source of the page to find the right id. -*By Jon Bratseth in June 2016*
\ No newline at end of file +*By Jon Bratseth in June 2016* |