>
>
> -----Original Message-----
> From: Joe Brockmeier [mailto:[email protected]]
> Sent: Thursday, October 18, 2012 6:35 AM
> To: CloudStack Developers
> Subject: [DOCS][DISCUSS] Some style / formatting issues in docs
>
> 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.
>
I'm not sure about this one, and here's why.
This sounds similar to how you don't need to say "Click the OK button".
Just say "Click OK." That's clear in itself, whether you apply any
formatting to the "OK" or not.
However, in the case of "open foo," I'm not sure it is safe to rely on
screen formatting. We can't guarantee that the readers can see the visual
clue, and "open foo" isn't unambiguous in itself. It could refer to opening
a file, a program, a folder, or something else.
Examples where the reader won't see the visual clue: if the CSS uses only
color to render that <filename> tag and the reader isn't able to see color;
if the reader is visually impaired and relying on screen-reader technology,
thus getting audio only; if someone takes the Docbook files for a
derivative product, then creates their own CSS that ignores the <filename>
tag.
>
> - 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)
>
I had thought <programlisting> was meant for multi-line code excerpts, and
<command> for inline commands. It seems to me as if <programlisting>
provides a valuable service here for those occasions when white space and
carriage returns need to be preserved.
I've recently seen some code like this, which seems like it might have too
many tags. We don't need to use <command> inside <programlisting>, as far
as I know. It causes visual clutter.
<programlisting><prompt># </prompt><command>start foo --server
<replaceable>your-server-here</replaceable></command>
... (5 more commands) ...
</programlisting>
>
> - 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.
>
We do need to refer to other steps by number quite often. I agree it's not
advisable to hard-code the numbers. Here's one way I have found to insert
an auto-generated step number reference in Docbook:
<listitem id="step-to-link-to">
<para>Text of the step...</para>
</listitem>
<listitem>
<para>See step <xref linkend="step-to-link-to"/> ...</para>
</listitem>
>
> - 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>
>
Joe, can you say more about why? I've hardly ever seen this done. I'm
perfectly content with notes that just look like "NOTE: Here's something
brief you should know that's helpful, but not essential." If a note is long
enough to need a title, I'd be inclined to make it a real paragraph or a
section instead.
>
> 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
> this:
>
> <note>
> <para>I've got some text here
> and it wraps oddly.</para>
> </note>
>
> Does anyone feel strongly that it should look like that?
I don't care strongly about line lengths in document files.
> 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.)
>
> Thoughts?
> --
> Joe Brockmeier
> [email protected]
> Twitter: @jzb
> http://www.dissociatedpress.net/
>
Joe, thanks for bringing up these questions. I've been more in the "wow, we
need to get the docs up" mindset and haven't yet devoted much brain real
estate to the "style guide" part of the task.
Which brings up the question: Do we want to start collecting items like
this, and call it a Documentation Style Guide?
Jessica T.
CloudStack Tech Pubs
