docs/1.6/styleguide/overview.xml

   1 <?xml version='1.0' encoding='UTF-8'?>\r
   2 <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"\r
   3   xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="overview">\r
   4   <title>Evergreen and DocBook</title>\r
   5   <section>\r
   6     <title>About our approach</title>\r
   7     <simplesect>\r
   8       <title>Overview</title>\r
   9       <para>This is the style guide for documentation produced for the Evergreen open-source library\r
  10         software project. This manual is intended to help everyone involved in the documentation\r
  11         "supply chain" by providing guidance wherever a decision about documentation formats needs\r
  12         to be made, from image size to file-naming conventions and the approved lists of tags and\r
  13         XSL stylesheets. </para>\r
  14       <para>This is a living document in a fairly new endeavor, so your feedback on areas that need\r
  15         correction or expansion is encouraged and warmly appreciated. </para>\r
  16     </simplesect>\r
  17     <simplesect>\r
  18       <title>History</title>\r
  19       <para>In May, 2009, the Evergreen Documentation Interest Group committed to single-source,\r
  20         XML, using the DocBook 5.0 documentation standard, for all Evergreen-wide documentation, and\r
  21         committed to working as a group. </para>\r
  22       <para>The rationales for this approach were as follows:</para>\r
  23       <itemizedlist>\r
  24         <listitem>\r
  25           <para>The Evergreen project needed to move past the gaps and duplicated efforts of having\r
  26             documentation written within local library systems and leverage its size and skills\r
  27             toward a common goal.</para>\r
  28         </listitem>\r
  29         <listitem>\r
  30           <para>The commitment to single-source documentation means that core Evergreen\r
  31             documentation would be could be repurposed as necessary into many different formats --\r
  32             one core set of files, many outputs.</para>\r
  33         </listitem>\r
  34         <listitem>\r
  35           <para>XML provides structure to a document and semantic "meaningfulness." </para>\r
  36         </listitem>\r
  37         <listitem>\r
  38           <para>The DocBook standard is a commonly-used documentation standard that has the\r
  39             advantages over other standards of relative ease of use and a long, well-established\r
  40             history of development and stewardship. DocBook is also the de facto standard XML schema\r
  41             and publishing tool set for a number of open source projects, so we will be able to\r
  42             capitalize on the work others have done before us.</para>\r
  43         </listitem>\r
  44       </itemizedlist>\r
  45     </simplesect>\r
  46     <simplesect>\r
  47       <title>DocBook 5.0</title>\r
  48       <para>DocBook 5.0 is the authoring language for Evergreen documentation. DocBook 5.0 provides\r
  49         a structured XML-based grammar for writing complex technical documentation. It is also an\r
  50         OASIS standard. The remainder of this style guide discusses how Evergreen uses\r
  51         DocBook.</para>\r
  52     </simplesect>\r
  53     <simplesect>\r
  54       <title>Our production model in a nutshell</title>\r
  55       <para>(Note: this primarily applies to documentation that is making its way into the Evergreen\r
  56         documentation XML toolchain for the first time. We have not yet developed a production model\r
  57         for revising XML documents.) </para>\r
  58       <para>\r
  59         <itemizedlist>\r
  60           <listitem>\r
  61             <para><emphasis role="bold">Documentation writers</emphasis> author Evergreen\r
  62               documentation in whatever format they choose (this is a guiding principal of the\r
  63               Evergreen documentation project), using the editors of their choice. While authors are\r
  64               encouraged to produce documentation in DocBook 5.0, we will accept new documentation\r
  65               in any form the author chooses to write it (and however "localized" it may be). Note\r
  66               that the DIG project will be providing heavily-commented template files for DocBook\r
  67               XML production. </para>\r
  68           </listitem>\r
  69           <listitem>\r
  70             <para>Authors submit documents to the <emphasis role="bold">intake team</emphasis>, who\r
  71               will submit the documentation to functional testing and revise content accordingly.\r
  72             </para>\r
  73           </listitem>\r
  74           <listitem>\r
  75             <para>If documentation needs conversion from its format to DocBook 5.0, the DIG\r
  76                 <emphasis role="bold">XML conversion team</emphasis> wrangles it.</para>\r
  77           </listitem>\r
  78           <listitem>\r
  79             <para>One the files are in valid, well-formed XML conforming to the DocBook 5.0\r
  80               standard, <emphasis role="bold">DIG XML editors</emphasis> (the human kind of editors)\r
  81               review the files for conformance with Evergreen documentation style guidelines.</para>\r
  82           </listitem>\r
  83           <listitem>\r
  84             <para>When the XML files are ready, the <emphasis role="bold">DIG transform\r
  85                 team</emphasis> members use a variety of back-end tools to process the files (or, in\r
  86               DocBook and XML terminology, <glossterm>transform</glossterm> the files) into HTML,\r
  87               PDF, and other formats. <emphasis role="bold">Web designers</emphasis> play a crucial\r
  88               role at this stage as well, creating and maintaining the Cascading Stylesheets (CSS)\r
  89               that make the documentation aesthetically pleasing and more user-friendly. Finally, a\r
  90               small group of <emphasis role="bold">"the buck stops here" editors</emphasis> move the\r
  91               HTML and PDF files into their folders on the website.</para>\r
  92           </listitem>\r
  93         </itemizedlist>\r
  94       </para>\r
  95       <para>\r
  96       </para>\r
  97     </simplesect>\r
  98   </section>\r
  99   <section>\r
 100     <title>Formatting XML</title>\r
 101     <simplesect>\r
 102       <title>Overview</title>\r
 103       <para>Documentation writers who author in XML generally fall into two camps: those who prefer\r
 104         a full-featured WYSIWYG editor with built-in validation tools, and those who prefer to code\r
 105         XML "by hand." </para>\r
 106       <para>DIG is neutral on this issue, but can recommend software for those interested in\r
 107         authoring, editing, revising, updating, or validating XML files. Documentation editors\r
 108         higher up in the XML chain will ultimately reformat all XML so it has appropriate indenting\r
 109         and wrapping. If you are using an editor such as oXygen, most of this formatting is already\r
 110         done for you by the software. If you are coding XML by hand, you are encouraged but not\r
 111         required to keep lines under 80 characters long, and to avoid leaving white space between\r
 112         elements. </para>\r
 113     </simplesect>\r
 114     <simplesect>\r
 115       <title>Validation</title>\r
 116       <para>More crucially than indenting and white space, the DIG would appreciate it if authors\r
 117         producing XML would attempt to validate their files prior to submitting them to ensure the\r
 118         markup is valid and well-formed XML that conforms with DocBook 5. However, if you run\r
 119         against insoluble validation problems, please do not let that hold you up; just submit the\r
 120         files and we will fix the problems and advise you of what we found. </para>\r
 121     </simplesect>\r
 122   </section>\r
 123   <section xml:id="info">\r
 124     <title>Other Resources</title>\r
 125     <simplesect>\r
 126       <title>DocBook References</title>\r
 127       <para>For more general references and familiarization with with DocBook, see the\r
 128         following:</para>\r
 129       <itemizedlist>\r
 130         <listitem>\r
 131           <para>\r
 132             <link xl:href="http://DocBook.org/">DocBook.org</link>\r
 133           </para>\r
 134         </listitem>\r
 135         <listitem>\r
 136           <para>\r
 137             <link xl:href="http://opensource.bureau-cornavin.com/crash-course/">The Crash Course to\r
 138               DocBook</link>\r
 139           </para>\r
 140         </listitem>\r
 141         <listitem>\r
 142           <para>\r
 143             <link xl:href="http://nwalsh.com/docbook/">Norman Walsh's DocBook page</link>\r
 144           </para>\r
 145         </listitem>\r
 146       </itemizedlist>\r
 147     </simplesect>\r
 148   </section>\r
 149 </chapter>\r