[Typo3-doc] DocTEAM first goal = the structure

[Peter Kindström]

Hi,
First of all I suggest that everyone (involved in this) should 
read Kaspers document: "Typo3 Documentation Organization".

It is mainly about Developers documentation, but many of his 
thoughts could, or should, be used for *all* documentation.

The down side is that this document is not very clear on how to 
really organise documentation! It makes clear of what different 
criterias and types of documents there are, but then it fails to 
tell us which of those we should use for structuring! :-(

But in his document he identifies four different criterias to 
categorize documentation around:
  - Relation (Core, Extension, Installation, Misc)
  - Target group (Users=Editors, Admins, Developers)
  - Type (Reference, manual, examples, tutorials)
  - Skill level (Beginner, Intermediates, Experts)

(I think that Relation could be changed to Subject and that ther 
could be more/other subjects...?)

-----------

My experience is that a structure should be based on ONE 
distinct critera. And I think it should be one of the above.

A few exceptions (max around 5 is my theory) can be tolerated, 
but the more consistent (to the criteria) the structure is, the 
easier it is for people to learn it - even if it isn´t thier 
preferred way of structuring!

And my theory is also that you can never get a structure that 
everybody likes. But you can get one that is easy to learn! And 
I believe that a consistent structure is easy to learn.

-----------

So, as a result of this, I recommend that you try to write down 
rules for where to put documents in the strucuture. If you get 
only a few rules (say 3-5 short sentenses) then it could/should 
be a good structure. But if you start with 2-3 rules, and then 
have to add many exceptions - then I would say it is a bad 
structure.

You should then take all the existing Typo3 documentation and 
try to put it into the structure by following the rules. If you 
still have 3-5 rules after doing that - and didn´t have to add 
rules for all documents to fit - then I think it is a good 
structure. Don´t forget to try to include future documents too.

----------

I have always tried to explain to people how I think when I 
structure things. But this is the first time I have been able to 
put it into words.

I believe this is the way I thought when I made my suggestion 
for the wiki structure. I used the "Target group" critera and 
did 3 or 4 exceptions: "Getting started", "Extensions", "Help, 
tips & troubleshooting" and maybe "Projects" (they aim at all 
target groups at the same time).
The other links (Doc matrix, About docs and News) are not really 
part of the *documentation* structure, but are necessary for 
other reasons.


/Peter Kindström