You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cloudstack.apache.org by Joe Brockmeier <jz...@zonker.net> on 2012/10/18 15:34:43 UTC
[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.
- 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
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? 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
jzb@zonker.net
Twitter: @jzb
http://www.dissociatedpress.net/
Re: [DOCS][DISCUSS] Some style / formatting issues in docs
Posted by David Nalley <da...@gnsa.us>.
On Thu, Oct 18, 2012 at 11:56 AM, Joe Brockmeier <jz...@zonker.net> wrote:
> On Thu, Oct 18, 2012 at 10:03:46AM -0500, Joe Brockmeier wrote:
>> On Thu, Oct 18, 2012 at 10:51:15AM -0400, David Nalley wrote:
>> > That said, our Java coding standards says lines shouldn't be more than
>> > 80 chars:
>> > http://docs.cloudstack.org/CloudStack_Documentation/Design_Documents/Coding_Conventions#Files.2C_Layout_and_whitespace
>>
>> Sure, but this isn't Java. If you look at, for instance, the upstream
>> Publican docs:
>>
>> http://git.fedorahosted.org/cgit/publican.git/tree/publican/Users_Guide/en-US
>
> Argh - didn't finish the thought.
>
> If you look at other projects using DocBook/Publican, they typically
> don't hard-wrap docs to adhere to programming language guidelines.
I'll take that as anecdotal.
Docbook the Definitive Guide shows a counter example:
http://www.docbook.org/tdg5/en/html/para.html
Additionally Gnome (which I rarely call out as an example, but...)
seems to use the same standard.
http://developer.gnome.org/gdp-handbook/stable/docbook.html.en#docbook-section
Re: [DOCS][DISCUSS] Some style / formatting issues in docs
Posted by Joe Brockmeier <jz...@zonker.net>.
On Thu, Oct 18, 2012 at 10:03:46AM -0500, Joe Brockmeier wrote:
> On Thu, Oct 18, 2012 at 10:51:15AM -0400, David Nalley wrote:
> > That said, our Java coding standards says lines shouldn't be more than
> > 80 chars:
> > http://docs.cloudstack.org/CloudStack_Documentation/Design_Documents/Coding_Conventions#Files.2C_Layout_and_whitespace
>
> Sure, but this isn't Java. If you look at, for instance, the upstream
> Publican docs:
>
> http://git.fedorahosted.org/cgit/publican.git/tree/publican/Users_Guide/en-US
Argh - didn't finish the thought.
If you look at other projects using DocBook/Publican, they typically
don't hard-wrap docs to adhere to programming language guidelines.
--
Joe Brockmeier
Twitter: @jzb
http://dissociatedpress.net/
Re: [DOCS][DISCUSS] Some style / formatting issues in docs
Posted by Joe Brockmeier <jz...@zonker.net>.
On Thu, Oct 18, 2012 at 10:51:15AM -0400, David Nalley wrote:
> > 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>
> >
> That said, our Java coding standards says lines shouldn't be more than
> 80 chars:
> http://docs.cloudstack.org/CloudStack_Documentation/Design_Documents/Coding_Conventions#Files.2C_Layout_and_whitespace
Sure, but this isn't Java. If you look at, for instance, the upstream
Publican docs:
http://git.fedorahosted.org/cgit/publican.git/tree/publican/Users_Guide/en-US
> That said, I am not necessarily married to this, but line lengths that
> hit 500-600 characters is undesirable in my mind.
Not sure that any arbitrary wrapping length is desirable, though.
Where's the cut-off?
Best,
Joe
--
Joe Brockmeier
Twitter: @jzb
http://dissociatedpress.net/
Re: [DOCS][DISCUSS] Some style / formatting issues in docs
Posted by David Nalley <da...@gnsa.us>.
> 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>
>
My XML OCD personality says that the above is wrong and instead should be:
<note>
<para>
I've got some text here that is no more than 80 chars long
and it wraps oddly
</para>
</note>
That said, our Java coding standards says lines shouldn't be more than
80 chars:
http://docs.cloudstack.org/CloudStack_Documentation/Design_Documents/Coding_Conventions#Files.2C_Layout_and_whitespace
That said, I am not necessarily married to this, but line lengths that
hit 500-600 characters is undesirable in my mind.
--David
Re: [DOCS][DISCUSS] Some style / formatting issues in docs
Posted by Jessica Tomechak <je...@gmail.com>.
>
>
> -----Original Message-----
> From: Joe Brockmeier [mailto:jzb@zonker.net]
> 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
> jzb@zonker.net
> 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