Thanks, DIG folken! I have just one comment/request: can we have the "command names", and by extension command line examples, be something like "bold monospace 8pt font face"? See, for instance, the "consolas" font in Google docs.
--miker On Wed, Nov 6, 2013 at 11:20 PM, Kathy Lussier <[email protected]> wrote: > Thank you for doing this Remington! I know I will find this page very > helpful when I'm creating/revising documentation. > > I don't know anything about the DocBook style guide. However, when we were > writing Evergreen in Action, we did have a couple of style rules we followed > to try to maintain consistency in the book. Maybe it can help with the style > guide for the official docs. The rules were in the notes section of the > booki software we used for editing the book. I've copied them below: > > Arrows: > > Command names: italicize > Defining terms: italicize > Window names and UI elements: bold > Images: class=border-img > NOTEs: <div class=note> > Contractions: spell'em out to err on the side of formality > Language: 'murrican > > > It wasn't in the notes, but I recall we also decided that chapter/section > headings should be in sentence case. > > I noticed you used -> for the arrow in your style guide. From what I have > seen, the -> has primarily been the convention in the official > documentation, and I would opt to go with it over what was used for the > book. The image and note classes don't really pertain to our official docs - > they were just classes we needed to address some formatting issues in the > book. > > For the language, I know we had a previous DIG discussion several years ago > in which we agreed that the document writer could determine whether they > would use the American or Canadian spellings of words. Basically, if you > take the time to create the documentation, you can decide to spell > catalog(ue) whatever way you like. For the book, we went in a different > direction because we thought consistency was needed there. > > Kathy > > Kathy Lussier > Project Coordinator > Massachusetts Library Network Cooperative > (508) 343-0128 > [email protected] > Twitter: http://www.twitter.com/kmlussier > > On 11/6/2013 4:05 PM, Remington Steed wrote: > > I have started a DIG AsciiDoc Style Guide, in anticipation of the coming DIG > hack-a-way. Anyone is welcome to edit and contribute ideas. Also, does > anyone have a copy of the old DocBook style guide that DIG used? It isn’t > available on the docs website any more, at least not at the link on the wiki > (http://docs.evergreen-ils.org/style_guide/html/). Maybe that could help us > formulate our new style guide. > > > > DIG AsciiDoc Style Guide > > http://evergreen-ils.org/dokuwiki/doku.php?id=evergreen-docs:dig_style_guide > > > > -- > > Remington Steed > > Electronic Resources Specialist > > Hekman Library, Calvin College > > http://library.calvin.edu/ > > > > > > _______________________________________________ > OPEN-ILS-DOCUMENTATION mailing list > [email protected] > http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation > > > > _______________________________________________ > OPEN-ILS-DOCUMENTATION mailing list > [email protected] > http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation > -- Mike Rylander | Director of Research and Development | Equinox Software, Inc. / Your Library's Guide to Open Source | phone: 1-877-OPEN-ILS (673-6457) | email: [email protected] | web: http://www.esilibrary.com _______________________________________________ OPEN-ILS-DOCUMENTATION mailing list [email protected] http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
