Re: docs & misc

[Anthony Aldridge <aa...@csc.com>]

Lesson 1 in How to Author A How-To should be: back up your work regularly
in case your computer crashes :-)

Tony




Mikhail Fedotov <mi...@kittown.com> on 06/28/2002 08:37:42 PM

Please respond to cocoon-dev@xml.apache.org

To:   cocoon-dev@xml.apache.org
cc:
Subject:  Re: docs & misc


Hi!

I've spend several hours writing an answer, and my computer
crashed... damn. So I've tried to be as much short and
practical as possible. It took two more hours. Damn. :)

> And yes, I've written guidelines about each of them. See
>   http://xml.apache.org/cocoon/howto/

About 'How to Author a How-To'.

Here is one obvious place there the SCORE could be applied
(with some mods), I'm talking about 'overview' section. The
application can be done in the form of blank with the
following questions: that is the situation where this howto
is useful (4example, large amount of static documents),
what do we want to do (enable caching), that do we hope to
get by doing that (faster response times), that could/is
preventing us from doing that (not enough memory) and that
steps must be done (changing config), and that will help us
to do that (different caching mechanisms implemented in
cocoon, with an option to keep cached documents on memory
or on harddrive).

You can judge by yourself where those questions are useful.
I've studied other parts of howto, score is all over the
place, but in most cases only one or two questions are
required, so the whole model isn't needed. And it isn't
needed in any other form except for those questions.

The next addition is the step-by-step guide on how to
create docs. I.e. there shouldn't be just a long verbose
list of guidelines, but the list of first 4-5 tasks to
complete first version of howto (and publish it), and
recommendations on it's future refining. Current list of
guidelines looks like the list of mandatory requirements
and distracts a bit. Well, 'distracts alot' will be more
correct. ;) Just complement it with minimalistic
instruction with a clear distinction between general
guidelines and steps to author an how-to. Now they are
mixed, and it is very funny to read in the _first_ (by
order) _step_ that it is actually the _last_ one. :)

> >If you could create advanced documentation as easy as
> >basicget-started-in-a-minute howtos, there would be more
> >advanced documentation. Document templates (with SCORE
> >installed in form of questions), blanks, any other
> >automation could help if implemented wisely.
>
> Is there an example of this anywhere on the web?

I doubt, except that you can find a book about history of
the whole idea of blanks. It is an interesting story and a
there are good examples of proper applying of blanks idea.
Bureaucracy is an example of incorrect applying.

If we are talking about docs generation for some already
written software, score is reduced to several questions
(mentioned above) that can help us to create an effective
blank, and that's it.

> <snip what="stuff about SCORE" why="need link" />

The net contains usage in therapy mostly. :) The model
itself is obvious enough to be reinvented and used under
different name in other contexts, but I don't know that
name.

> Still, if people know enough about Cocoon to write
> docs, they should be comfortable creating a
> document.dtd-compliant XML pages as contributions and
> submitting via Bugzilla. We have How-To instructions for
> all of that.

I fear they won't go for it. You require too much
motivation from them. Let's wait for Forrest & forms...

> Send us a link about SCORE, or about web-based approaches
> using SCORE, and I'll be more than happy to have a look.

I've reduced it to some basic question for this particular
case of writing docs; otherwise we could end up discussing
it for too long. It wasn't a wise decision to mention SCORE
here, my apologies. Hope those questions will be useful. :)

Mikhail

---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org








---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org