Format for procedures

Tue Nov 14 17:06:46 UTC 2006

On Tuesday 14 November 2006 10:39, Stoos, Ralph wrote:
> All,
>
> I would like to suggest a change to the format of procedural
> instructions.  I realize that this change will make for more changes,
> but it benefits the user in two ways.  One, it allows the Table of
> Contents to have a high level of granularity for faster access.  Two, it
> gives the uses "checkpoints" to know where they are in the process.

We might be one step a head of you, or maybe flat out equal right now. We are 
currently discussing ways in which we are going to change the current 
documentation in order to make it easier to use, and to make it a lot more 
helpful.

> I took this paragraph below from the Desktop Guide as an example.  By
> all means tell me I am crazy, full of it, or just wrong.  I have used
> this format with great success in a number of publications I have
> authored that are procedural.

You might be crazy, but that isn't for any of us to decide, plus I would 
charge an arm and a leg to diagnose you ;) From what I have seen, your format 
is a much better way to describe the process you covered w/o a doubt.

> Further, I do not wish to insult anyone's work.  It occurs to me that
> these documents are put together by a small group and done under great
> time pressure.  This is not a rip, merely a suggestion for discussion.
> I have guessed at a couple things because I run KDE and use K3B most of
> the time.

Constructive criticism should never be an insult.

> This note will no doubt come through with a lot of the formatting
> stripped off.  I bold proper names and button names to have them stand
> out.  I also number steps so users can track where they are.  Since I
> have broken out audio CD vs. Data CD procedures, they should appear as
> separate entries in the TOC and make a specific want by the reader
> easier to find.

We leave the stylization and all of that to the Style Guides we follow (based 
off of KDE and GNOME guides). But your example is easy enough to follow 
without any formatting.

[snip the current way]

> 3. Burning CDs
>
> When a blank CD is inserted in a CD or DVD burner drive, a dialog will
> open to ask the user to choose the type of CD or DVD they wish to write.
>
> To burn an audio CD:
>
> 1.	Click the  Burn Audio CD entry.  The Serpetine application will
> be started.
> 2.	You may drag and drop music files from the File Manager or
> selected the desired files and click the Add button.
> 3.	You will be prompted to select the size of the CD media (21, 74,
> 80, 90 minutes).
> 4.	If your selections exceed the size of the chosen media, you will
> be warned.
> 5.	Click the <Write to Disc / Burn?> button to start the process.
> 6.	When the write operation is finished, eject the CD.
>
> To burn a Photo or Data CD:
>
> 1.	Click Burn Data CD.  The CD/DVD Creator included in the File
> Browser application will be started.
> 2.	You may add files from the File Manager as long as you have
> permissions to the files or directories you choose.
> 3.	Click the Write to Disc button.
> 4.	You will be prompted to select the drive that contains CD/DVD
> media.
> 5.	You will be prompted to choose a volume name of the writable
> media.
> 6.	You will be prompted to select the write speed for the media.
> 7.	Click the Write button to start the process.
> 8.	When the write operation is finished, eject the CD.

I agree this is better than the current, and we can guarantee that the current 
documentation we are planning for the 7.04 release will hopefully fix all of 
this. Speaking of that, if you have any free time, say the next 6 months ;), 
we could definitely use the assistance, and would greatly appreciate any type 
of help you can provide. We will be working out of the Documentation SVN 
Repository, Trunk, if you want to follow along with the work we are doing. I 
wouldn't expect to see much within the next month or so, but after all of the 
meetings clear, and work begins, any suggestions/comments/ideas or whatever 
that you may have, we would greatly appreciate. If you are unfamiliar with 
our SVN Repository, please refer to the wiki page 
https://wiki.ubuntu.com/DocumentationTeam/Repository for more information.

Thanks for the email Ralph, and we definitely look forward to hearing more 
from you in the future ;) Take care!

-- 
.:Richard Johnson
.:nixternal at ubuntu.com
.:ubuntu.com .:kubuntu.com .:edubuntu.com .:xubuntu.com
.:http://nixternal.ubuntu-rocks.org
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20061114/441f02fe/attachment.pgp>