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
