[OPEN-ILS-DOCUMENTATION] DIG Style Guide rough draft

[Kathy Lussier]

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
klussier at masslnc.org
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
> OPEN-ILS-DOCUMENTATION at list.georgialibraries.org
> http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://list.georgialibraries.org/pipermail/open-ils-documentation/attachments/20131106/e8e949b3/attachment-0001.htm>