added guidelines

README.md

@@ -1,6 +1,6 @@
 # Nitrokey Documentation
 
-### Local build
+## Local build
 
 Be sure to have a recent python installed, then:
 
@@ -13,7 +13,7 @@ The (english) result is to be found in `dist/en`, to show run:
 firefox dist/en/index.html
 ```
 
-### More Makefile Targets
+## More Makefile Targets
 
 * `clean` will clean up generated files
 * `cleaner` includes `venv/`
@@ -22,6 +22,35 @@ firefox dist/en/index.html
 * `docs` first target, default, will quick-build the english docs
 * `pkg` assembles a package for deployment in `dist` (unused)
 
-### Localization
+## Localization
 
 You can find the locales for this repository here: https://github.com/Nitrokey/nitrokey-documentation-data
+
+## Guidelines
+
+Follow these guidlines to write uniform and comprehensive documentation.
+
+### Headlines
+
+When writing title case headlines, major words are capitalized while minor words are lowercase.
+
+* Major words are nouns, verbs, adjectives, pronouns, adverbs, and basically any word four letters or longer.
+* Minor words are conjunctions that are three letters or less (e.g. and, or, nor, but), short prepositions (at, by, for, in, of, on), and all articles (a, an, the).
+
+In addition, the following words should be capitalized under title case:
+
+* The first word of the title — including minor words.
+* The first word after any punctuation (semicolon, em dash, end punctuation, etc.) except for commas.
+* Words four letters or longer (With, After, Then, etc.).
+* All major words — including post-hyphen words (“Last-Minute” as opposed to “Last-minute”).
+
+Title case headline examples:
+
+    The Fargo Forum Found Fresh Fish
+    7 Reasons Your Content Needs a Great Headline
+    Local Pizza Shop Claims 'Best Pie in Town'
+
+### Boxes
+
+Boxes like note, warning, and important should only contain added information.
+The author has to make sure, that if one would imaging removing all boxes in a certain article, it should still make sense and lead to the expected goal.