[TYPO3-doc] DocBook: first sample manual

[François Suter]

Hi Michael,

Thanks for your detailed feedback.

> - Line 23 + 33: is the date updatable automatically – maybe upon
> rendering? Would save some time ...

Good question. I don't know. I would expect this to be possible upon
rendering, which would also be the really correct date.

> - In general: As writer would I always have to add a new section even
> if I just wanted to add a subheadline? What if I just wanted to
> structure my text within my section / without creating a new
> section?

Sections are not mandatory I would say. If you are writing a very small
chapter, you should just put a few paras and be done with it. That might
be especially true for extension manuals. I wouldn't expect formal
manuals to have such chapters.

Furthermore it is perfectly ok to have a couple of introductory
paragraphs that sit before sections (as there is in Chapter 1).

Was that your question?

> - Line 60 et sqq.: "new" is a pretty meaningless word (from which
> point of time is "new"?), so this section could offer more tags for
> the historical version-numbers (of TYPO3 or the EXT) + the new
> features within each version. But this would lead to kind of a
> changelog-style .. don't know if this is what you'd like.

In this case "new" is supposed to mean "what has changed since the last 
major version". I agree that it may be a bit fuzzy, but we definitely 
wanted to avoid turning this section into a full-blown change log. The 
idea is to refer people to the change pages in the wiki, when available 
and when more details are needed.

To clarify this section it is ok to mention TYPO3 or extension version 
numbers, but it should be kept short.

> - Line 125 et sqq.: To preserve consistency over all documents (including
> ext-docs) and offer an easy + clear handling for writers I would
> reduce the notice-tags to only caution (or warning) and note (or
> tip/important). I think otherwise these tags might get used for
> different meanings and lead to confusion for readers.

I think that caution and warning are really close and I would use only 
one of them. Looking again the admonitions after your remark, I agree 
that we could probably also use only one of "tip" or "note" and not 
both. As for "important" I would keep it because it is meant to be used 
to really reinforce a notion that was presented just before. Of course 
you could say this is some form of caution, but for me "caution" is more 
about warning the reader about potential pitfalls.

But I agree with you that there might be confusion in the use of 
admonitions by manual writers.

>  - Line 230 et sqq: I couldn't find a manual in which a function is described in
> detail that much ... I'd just give an overview regarding the
> functions, as you say in your remark and then point to the API.

Yep.

> - Line 363 et sqq: I think it depends on the target group if acronyms
> and so on could be useful. It would be interesting how these tags get
> handled: is there  kind of a glossary with which the acronyms and
> abbrevs get linked automatically? Then it would be nice have such a
> functionality especially (only?) for newbies.

I'm not sure if this can be handled automatically. One path to 
investigate might be whether we could build a DocBook glossary and then 
import it into an extension like "contagged" which would then be used on 
the HTML version of the manual pages. Otherwise I think it's not so 
interesting to use these tags.

Of course it is still useful to build a glossary, which could be 
included in the manuals that need it.

> - Line 392: I would replace "Next steps" with "Further resources", which makes it clearer
> what to find in this chapter / section.

This was discussed quite a bit previously and we settled on "Next 
steps". Thinking about it again I would say the appropriate naming 
essentially depends on the context. I think we could differentiate:

- use "Next steps" in tutorials, where the resources pointed to are 
really about what steps you can take next after having been through the 
tutorial
- use "Further resources" for guides and core manuals, where it's really 
more about a list of references to useful stuff.

Other opinions?

> Minor remarks: - Line 132 + 138: two typos ;)

OK, corrected.

Cheers

-- 

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