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

[Mike Rylander]

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 <klussier at masslnc.org> 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
> 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
>
>
>
> _______________________________________________
> OPEN-ILS-DOCUMENTATION mailing list
> OPEN-ILS-DOCUMENTATION at list.georgialibraries.org
> 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:  miker at esilibrary.com
 | web:  http://www.esilibrary.com