[TYPO3-doc] DocBook: first sample manual

[Thomas Schraitle]

Hi François,

Friday 18 February 2011
> [...]
> Anyway it's good that you comment here for discussion :-) However it
> would certainly make sense for you to have commit rights at some point.
> The first step is to create an account on typo3.org:

Ok, done. :)


> [...]
> > 2. About acronyms and abbrevs
> > I'm not sure what you will gain from this, but... you *could* use them to
> > add them to the index page, if needed.
> 
> OK. I didn't think about the index page yet, I must say. Is there
> anything important to know for building good index pages?

Consistency. :)
The O'Reilly indices are usually pretty good so I would take these as an 
example. It is also a good idea to give your readers different "paths" to 
access your indexterms. If you have, for instance, the primary term 
"declarations" and the secondary term "element" it may make sense to switch 
the order and insert also an index for element > declarations.

Apart from that: To automatically insert indexterms for acronyms or abbrevs, 
need a separate, intermediate step in your tool chain.

 
> [...]
> > 4. Is it worth using<tag>screen</tag>?
> > Definitly! The screen element is very useful if you run command line
> > tools and view their outputs. The use of prompt is debatable, but
> > replaceable is something that I need very often.
> 
> [...]
> I find using the prompt tag is a bit overdoing it, especially since I'm
> not sure we would really differentiate it upon rendering.

Well, it depends (the usual consulting answer! ;) )
If you have to distinguish between an administrator and a normal user it may 
make sense to insert the prompt to distinguish between the two. Using prompt 
renders into <span class="prompt"> for (X)HTML which can be styled through 
CSS. If this is really worth for your documents, I'm not sure. Probably it's 
too much.

 
> > 5. Procedures and Lists
> > Maybe this depends on your styleguide, but titles in your procedures are
> > very helpful. Especially when you refer to a procedure, it's always a
> > bit more userfriendly to see "Procedure 4.2, 'Using DocBook'" instead of
> > a bare "Procedure 4.2" without knowing what is it all about.
> 
> You're right. I missed that. You're mentioning numbers, is there some
> automated numbering? Is it done on rendering.

Yes, it's numbered automatically by the DocBook stylesheets. What I forgot to 
mention: It's automatically integrated into the list of procedures. In my 
opinion, this is extremly helpful for readers.


> [...]
>
> > For me it seems some of the above items are some kind of styleguide
> > issues. :) Some could be enforced with a customized DocBook schema or
> > some written "how to write TYPO4 documentation".
> 
> The way I see it, we would use a customized schema just to "hide" tags
> that we're not going to use (to make it simpler for editors) and the
> rest would indeed be guidelines.

A customized DocBook schema would probably give some guiding help for your 
writers. The problem is always how much you need/want to deviate from DocBook.

Although DocBook 5 has reduced the amount of tags (it's even less than DocBook 
4) it might be sometimes a bit too much. I would recommend to remove 
unnecessary tags/attributes instead of adding new ones. This way it is a 
subset of DocBook. If you don't have your customized DocBook schema at hand, 
you can still validate it with the original DocBook 5 schema.

You probably know that already, but some rules can not be enforced through 
schema customization (how you write, when to use which tag, etc.)

 
> [... Structuring Documentation Repository ...]
> I have already received input by a couple of people and
> I have my own ideas. I need to write this all down and start a separate
> thread for this topic.

Ok, I'm curious. :)


Tom