[TYPO3-doc] DocBook: first sample manual

[Michael Bakonyi]

Hi Francois,

Am 17.03.2011 um 21:05 schrieb François Suter:

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

Kind of, yes. But especially for an example xml for EXT-developers I would add some example headlines aswell. I guess it's possible to add headlines like it's done with HTML, right? This often bothers me while reading extension-manuals: the detailed structuring within a chapter. Often headlines are just paras and therefore not visible as headlines which makes reading / understanding the text a bit difficult sometimes.

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

Yes, I think this should be added. Or just take your headline from above ("what has changed ...") which pretty much describes the following section.

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

Yes, interpretations might vary for caution and important. I would keep it simple and skip one. After thinking about it again I would just keep important which can stand for warnings aswell.

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

Ok you're more experienced in documentation, I believe in nearly everything you say. ;)

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

Can you give an example for "Next steps"? Scenario as reader: I'm finished with a tutorial so e.g. I've got a working T3-installation now. What could be my next steps? Maybe I'd like to add some extensions then within 'Next Steps" there could be a link to the repos. I could play around with the config, then there could be a link to the TSref-doc ... I can't imagine an example where "Further resources" wouldn't be a better wording. But maybe it's too early in the morning. ;)

Cheers,
Michael