[haiku-doc] Haiku User Guide - Guidelines
- From: Humdinger <humdingerb@xxxxxxxxxxxxxx>
- To: Haiku Documentation ML <haiku-doc@xxxxxxxxxxxxx>
- Date: Sun, 28 Dec 2008 18:42:04 +0100
Hi all,
in order to have a consistent user guide, we should work on a kind of guideline. Since
there's already quite a lot of documentation, it's sensible to try to "blend in", esp.
since there haven't been any negative reactions so far AFAIK. Of course, if our discussion
leads to certain style changes we'll convert the existing documents accordingly.
Once our guideline is done, it should go up to the other "Haiku Documentation" at
http://www.haiku-os.org/documents/
Here it goes:
General:
* Write conforming to XHTML 1.0 strict standard (see e.g.
http://xhtml.com/en/xhtml/reference/)
* Address the reader directly, avoid using passive, e.g.:
Not OK: "The file can be opened by clicking..."
OK: "Open the file by clicking..."
* Try to "blend in" with the rest of the documentation, by having a look at how some
layout things were done in other topics.
* Feel free to use the mailing list to point out improvements. Nothing's written in
stone... just XHTML.
Images:
* PNG with transparency (non-rectangular, tabbed windows), closely cropped
* Try to make images, esp. their width, as small as possible.
Text style:
* [i] Pref/App names italic, e.g. "DeskCalc", if that particular app isn't the subject of
that topic. System components like Tracker/Desktop, Deskbar or Terminal aren't italicized.
* [i] Menus italic, separate sub-menus with "|", e.g. "File | Open"
* [i] Buttons italic, e.g. "Apply"
* [tt] CLI commands monospaced, e.g. "checkfs"
* [tt] Paths monospaced, e.g. "/boot/home/config/"
* [tt] Keyboard shortcuts monospaced, all capitals, e.g. "ALT+C"
* Terminal in/output in a special pre-block; <pre class="terminal"></pre>
Regards,
Humdinger
--
--=-=--=-=--=-=--=-=--=-=--=-=--=-=--=-=--=-=--=-
Deutsche Haiku News @ http://www.haiku-gazette.de
Other related posts:
- » [haiku-doc] Haiku User Guide - Guidelines - Humdinger
