[TYPO3-doc] DocBook: first sample manual

[Thomas Schraitle]

Hi François,

Thursday 17 February 2011
> [...] I have a first sample DocBook-based manual for starting 
> the discussion about document structure. [...]

Congratulations! Well done! :-)


> [...]
> So please just concentrate on "manual.xml" for now and make your
> comments/remarks/etc., on anything you find good, bad, missing, could be
> improved and what not.

As I don't have commit rights I take the liberty to comment here. :)  Sorry, 
my comments are in no particular order, but I hope they are useful for you:

1. Links
I've seen something like this:

 <link xlink:href=
    "http://typo3.org/download">http://typo3.org/download/</link>

This is of course valid and possible, however a little bit verbose. If the 
href and the content of link are the same, the whole link element can be 
simplified like this:

 <link xlink:href="http://typo3.org/download"/>

In my opinion, it's a bit easier to read. The DocBook stylesheets creates the 
necessary link automatically. No need to repeat yourself. :)

I would suggest to use only an empty link element and use text in links when 
you _really_ need it. For example, let's focus on the following paragraph:

 For creating screenshots, refer to the <link 
  xlink:href="http://wiki.typo3.org/..."
  >screenshot guidelines</link>.

I would rephrase it like this to avoid links with text:

 For creating screenshots, refer to the screenshot guidlines at
  <link xlink:href="http://wiki.typo3.org/..."/>.

It's only a "minor issue", but I think it will improve consistency over all of 
your supported output formats. Probably a styleguide issue...


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.


3. Screenshots
You've wrote screenshot/info/title. This is of course valid DocBook, but it's 
a bit verbose. If you don't use any other (meta)elements inside info, better 
just omit the info element and use screenshot/title.


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.


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.


6. Remarks
I miss your remarks in remarks. ;) I use remarks very often to help me 
remembering important things. The big advantage is it can be switched on or 
off!
So it is still in your XML code, but not necessarily in your output format. 
That makes it very easy to disable remarks for the final version. This can't 
be done with pure XML comments.


7. Admonitions (Caution, Tip, ...)
You've "definied" the title as optional in admonitions. This can be done, but 
I would suggest not to do so. How admonitions have to be written are already 
definied in some national and international standards (ANSI Z536.6?).

This is merely a question of a styleguide than an issue with DocBook. However, 
I think it's more userfriendly to have a speaking title so the reader can 
decide if it's worth to read.


8. Preface?
Maybe you move the credits section into a preface? There you can add more 
information about where to obtain the source code, some typographical 
conventions, etc.


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".

 
> I haven't yet toyed with id's and cross-references, but it's a topic
> that we will have to broach on very soon. As far as I understand it, it
> will be closely related to the structure of our document repository,
> which is also a hot topic to solve.

That's a good question. Depends on if you want to have each book separated in 
one directory or everything in one place. Do they share some code or are there 
entities on their own?

Maybe you want to use the set element here? This combines several books under 
one "umbrella". This makes it possible to xref from one book into another. If 
you separate them, this will not work anymore. In that case you need olinks, a 
very obscure linking mechanism.

 
> As a kind of conclusion to this very first step, I would like to say
> that I pretty much enjoyed working with DocBook. [...] 

:-)


Cheers,
  Tom