[TYPO3-doc] DocBook: first sample manual

[Michael Bakonyi]

Hi Francois,

>> I have just committed a new version of manual.xml to the repository [1].
> 
> Any opinions on the topic? I would particularly like to hear of those accustomed to working with the current official documentation. Do you feel at ease with the proposed sample manual?

thanks for the reminder. :) I've had a look at the structure and here are my remarks and questions so far – I apologise in advance for remarks which are clear to everybody here already or needless as I'm new to the hole Documentation-stuff:

Questions:
- Line 23 + 33: is the date updatable automatically – maybe upon rendering? Would save some time ...
- 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? 

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

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

Cheers,
Michael











-- 
civit

Michael Bakonyi
Wieblinger Weg 19/1
69123 Heidelberg

+49 6221 7503949
http://www.civit.de

Am 11.03.2011 um 14:12 schrieb François Suter:

> Hey people,
> 
>> I have just committed a new version of manual.xml to the repository [1].
> 
> Any opinions on the topic? I would particularly like to hear of those accustomed to working with the current official documentation. Do you feel at ease with the proposed sample manual?
> 
> I would rather have comments now than complaints later ;-)
> 
> BTW in the latest version in the repository, I have added an id attribute to the sample procedure. I think this is important so that procedures can be referred to with unchanging URLs.
> 
> Cheers
> 
> -- 
> 
> Francois Suter
> Cobweb Development Sarl - http://www.cobweb.ch
> _______________________________________________
> TYPO3-project-documentation mailing list
> TYPO3-project-documentation at lists.typo3.org
> http://lists.typo3.org/cgi-bin/mailman/listinfo/typo3-project-documentation