[TYPO3-doc] DocBook: first sample manual

[François Suter]

Hi Tom,

Thanks for your feedback.

> 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:

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:

https://typo3.org/community/your-account/loginlogout/user-account/

Those accounts are synced with the Forge site and the SVN repo.

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

Good to know, it's indeed simpler.

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

Sounds good to me.

> 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?

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

Indeed I'm not sure the info is really useful in this case. I just 
followed the example in the book :-)

> 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'm sure the screen tag is useful. I meant that in the sense that we 
don't have much screen output in general in the TYPO3 documentation. But 
we could have some, so I guess it makes sense anyway.

I find using the prompt tag is a bit overdoing it, especially since I'm 
not sure we would really differentiate it upon rendering.

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

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

Brilliant, I had missed that! This is extremely convenient. I'll move my 
remarks to remarks then :-)

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

Sounds reasonable.

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

Another tag that I missed. It makes sense to use it. That's also a very 
good point about using DocBook, it forces us to be more strict with 
regards to the structure of our documents.

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

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

I guess we definitely want to be able to user xref as much as possible, 
but of course that raises questions about the structure of the 
documentation repository. As I said it'a topic which we should start 
discussing soon. 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.

Cheers

-- 

Francois Suter
Cobweb Development Sarl - http://www.cobweb.ch