forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ferdinand Soethe <samm...@soethe.net>
Subject Re[2]: (howto DTD) List of open ended threads ... to be extended!
Date Wed, 17 Nov 2004 08:33:55 GMT


Dave Brondsema wrote:

DB> The HowTo DTD is a simple document we developed for Forrest.  If you
DB> want complete functionality, DocBook was designed to handle exactly
DB> that.  See if it fits your needs.

Well, my point is, that we have a HowTo-DTD that should be used to
write HowTos (and that I find very useful). So using another dtd is
neither required nor really what we want, is it?

The only issue that I have with it is, that there is no distinction
between the instruction-part of a step and other paragraphs explaining
the result of the step or introducing the instruction.

And in a dtd that was specifically created to write howtos I think that
is vital. Not just to be able to render it differently (which can be
accomplished with style as well) but also because XML should express
function as cleanly as possible.

And an instruction like "Start your Firefox Browser and open the
Forrest you'd like to work on/play with." is clearly something else
than a paragraph explaining the result of following the instruction
("The page you have pointed to will show up in Firefox's main
window.").

Apart from these theoretical concerns, I think it would add usability
to our HowTos if steps looked something like this (see included image,
the icon could be improved).

If is after all very common practice to outline instructions that way.
You see it in practically every book.

And finally, having steps extended by an instruction element will also
help howto-authors as it clearly indicates that there should be an
instruction in each step.

And here I quote from the HowTo-HowTo:

DB> Describe the Steps of your How-To
DB> 
DB> In a precise, step-by-step approach, walk your reader through the
DB> process. Make sure your reader can reproduce your intended result
DB> by following your exact steps. Make the learning process efficient
DB> by supplying sample code snippets or configuration details as
DB> necessary.

Sorry this got so long, but as a technical writer, I take these issues
very seriously and perhaps sometimes being a bit stubborn about it.

Doesn't mean it should happen that way ...

--
Ferdinand Soethe
Mime
View raw message