|
|
Posted by Patrick Ben Koetter on 06/12/46 11:20
* Mark Rogers <mark@quarella.co.uk>:
> Based on what you said you obviously looked in the manual and the archives
> for help before you tried this list for help on this one.
>
> Since this must be one of the most commonly asked questions, the current
> documentation is obviously not doing a very good job on this subject. So,
> can you suggest (from your own point of view) how this could be made
> clearer?
Basically the documentation is good, because it lists functions, most of the
parameters that must or may be used and gives examples on how to use the
functions.
I would work on the structure of each page to make it more consistent and I
would take a users/developers perspective to order elements within each page.
Something along these lines to answer someones questions:
Functionname
+ Purpose of function
(Is this what I am looking for?)
+ Description of Attributes and values that my be used in conjunction with the
function
(What can I do with it?)
+ Examples
(How would I use this function? Is there something I can reuse or work from?)
+ Text that explains the goal of the example
(Okay. This is what I am about to see.)
+ Data the Example uses to operate
(ah! That's the <insert> data they use in the example. It looks like mine.)
+ The example itself
(Okay. That's where the parameter comes in I did not understand fully in
the parameter listing)
+ Output the example produces
(It works!)
This said here's a comparison to language.function.section.html:
+ It starts with a table. I need to scroll down to find out what section is
useful for
+ It says what I can use it for.
+ It _doesn't_ say what I cannot use it for nor does it tell me what the
alternative would be. A "caution:" or "note:" would be fine to catch the
FAQ.
+ There are examples, but I don't see an example of the array that is used for
the examples.
+ The examples carry comments that I'd rather like to see in an introductory
paragraph of the example.
+ The example mixes code and output. This is DocBook DTD, right? I'd use
<programlisting> and <screen> to split code from output.
> Personally I'd stick a big red note against {section} saying something to
> the effect of:
>
> In most cases, and in ALL cases involving associative
> (non-numeric indexed) arrays or numerical indexes
> which don't increment from zero, you should use
> {foreach} rather than {section}.
Do I have a choice? If not I'd say "must" instead of "should". ;)
> Of-course a lot of people won't read it anyway, but at least those who do
> will avoid this pitfall?
Yes, it would have saved me some hours and of course the feeling I'm a total
goof.
> I worry that for every person who gets stuck here and mails the list there
> must be someone who tried Smarty and gave up because they couldn't make it
> work.
I don't worry. Of course, if you want to gain more momentum for Smarty,
documentation that excels other projects is always a good way to get that.
I do a lot on the Postfix mailing list. When Wietse Venema reworked the
documentation for Postfix and incorporated many FAQs into the new
documentation the number of requests on the mailing list decreased
significantly, while the number of people using it rose.
Of course there's always the one or the other who's entry level is so low that
they don't understand how to use Postfix, because they have no plan how mail
works. Those are the ones that usually cannot understand the documentation as
well. But that's another problem. This is where books come in.
p@rick
P.S.
If you are not in a hurry, I'd be interested to help you with the
documentation because that's the way I contribute to Open Source.
At the moment I already have two (Open Source) documentation
projects to work on. I guess I'd be ready to help end of August.
Navigation:
[Reply to this message]
|