incubator-cloudstack-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Joe Brockmeier <>
Subject [DOCS][DISCUSS] Some style / formatting issues in docs
Date Thu, 18 Oct 2012 13:34:43 GMT
Hey all, 

In going through the release notes I've found a number of style /
formatting issues I wanted to bring up for discussion. 

- I've noticed a lot of instances where filenames are discussed, but the
<filename> element is not used. Instead of writing something like "now
open the file "foo"" it's *much* better to just say "open
<filename>foo</filename>" - the Publican formatting makes it clear that
you're talking about a file and it's a good visual clue to the reader. 

- Use <command> instead of <programlisting> when you're directing the
reader to enter a command. The programlisting element calls for
DocBook/Publican to assume the text that's following is to be formatted
*exactly* as it is in the file. The result is some horrendous layout
when it's not meant to be formatted that way. (Think the <pre> element
in HTML)

- Please warn users ahead of time if something might break, not after
you've instructed them to run a command. I've found a few instances of
"if Y happens after you do X, then..." - No. Tell them what the
consequences might be before they run a command or take an action. Some
readers, shocking as this may seem, are going to just step through
everything without reading the whole guide first. 

- Speaking of which, let's remember to remove sentences like "if foo
breaks, contact support." ;-) 

- Don't use hard-coded instructions. e.g. writing "step 2" when the
steps are being generated by <listitems> that very well may change at a
later date. 

- Double-check commands for accuracy. I found a doozy of an instruction
using sed in the release notes that 1) is way more complicated than it
ought to be and 2) simply doesn't work as written. 

- Use <title> with notes and warnings. e.g.:

<note><title>When Writing Notes, Use Titles</title>
<para>My note goes here</para></note>

I'd also like to discuss the formatting / wrapping of the files
themselves. The release notes are hard-wrapped right now so that there
are line breaks at about 80-100 columns even if it means something like

    <para>I've got some text here 
    and it wraps oddly.</para>

Does anyone feel strongly that it should look like that? It results in
some really, really wonky results if you're using a terminal at a very
wide or very narrow width. (And since many of us either work on laptops
with limited real estate, or on big displays with lots of real estate,
assuming anything like a standard column width is dicey, at best.) 

Joe Brockmeier
Twitter: @jzb

View raw message