DocumentationStandards

Here is a list of proposals for documentation standards for the User Manual (most important for DocBook xml and content)

DocBook tags we should use

• <book> - main tag encapsulating the whole book
• <part> - For larger sections (e.g. "Menus", etc; should only be a few of these in the book)
• <chapter> - subsections of a part (e.g."File" menu)
• <section> - subsections of a chapter (e.g. "Save" menu item)
• <para> - encapsulating any subsection of a chapter that needs a distinction from the preceeding and proceeding text (textual paragraphs, text content withing each list item or procedural item, etc)

(are we keeping these?)

• simplesect
• <guimenuitem> - is for final menu, for example "save as" in the "file <guimenu>
• <guilabel> - stands for any label at any places : Fill at the bottom or X property ...
• (keeping them is interesting : at export it is easier to applie specific formatting if they are tagged.)
• <emphasis> - ?
• <accel> - ?
• <keycap> - ?
• <keycombo> - standard key combination for a command (keycombo is to define a key combination for ex Ctrl+S where Ctrl is a keycap and S another one)
• i would also keep accel, keycap, and keycombo which are different ways of reaching a command, and having them it is also easy to build a accel list, keycombo list.

• add the tag-tree for pictures especially screenshots and icons (for tools and cursors)

maybe http://www.docbook.org/schemas/sdocbook/elements.html?

http://live.gnome.org/ProjectMallard - not much there

Basic Structure of a Part

• title+Intro+screenshot+Activation+Procedure+Additional infos+Links

<part> <title></title>

<chapter> <title></title>
 <section> <title></title>
  <para></para>
 </section>
<chapter>

</part>

Miscellany

• Links to sections should be named the same as the section title, except don't use caps and replace all spaces with dashes, e.g., the link for section "Menu Bar" would be "menu-bar".