[TYPO3] Documentation nightmare

[Peter Kindström]

Hi again!
> I would love to hear from you or doc team how a developer (me to be 
> exact) can help to rewrite such document as FTB? How this work can be 
> organized/divided? I cannot imagine it :( I am quite sure I can get hold 
> of FTB ownership from Kasper, so we really can update it.

Sorry, this posting is long....

First of all I think the docTeam should worry more about doc 
structure, managing and overview than about single documents. 
But of course the docTeam should also give some advise in 
matters like this!

How to organise the work? Hmmm, first of all there has to be 
_one_ person _responsible_ for the work - the docOwner. He/she 
desides who writes what, when it is ready and, if people 
disagree, deside which way to go.

Then I would make a draft wiki page, with just the headers 
(=topics) of the document. I would then move those headers 
around, add and delete some to get a well structured skeletton 
with simular topics near each other. Here other people should 
have the opportunity to particpate.

When all suggestions have been considered (not necessarily 
implemented :-) ) the docOwner comes to a point where he/she 
should say "this is the structure we will use - lets go on 
writing".

The next step would be to fill the space between the headers 
with actual text and pictures. Here you could assign different 
parts/header to different writers.

As I writer I would start by copying text from the old document 
into the right place/header on the wiki page. Then I would add, 
delete, update and change the text as needed. I would also have 
to rewrite some text so it fits together with the headers/topics 
before and after.

Durig this stage there will propaply be suggestions to move, add 
or delete headers/topics but if and how it should be done should 
be up to the docOwner to decide. (Otherwise you could go on with 
this forever. You can always revise the document again later.)

When there are text within all headers, _one_ person have to 
check the document for consitensy. It propably requires some 
editing too, because different people write in different ways 
and you dont want the reader to notice that.

Finally you should get a last review, to correct typos, that the 
right words are used and so on. And when that is done, the 
document is ready!

--------

This is of course in theory. You can probably do it in a much 
simpler way. But I believe the structuring phase (with just 
headers) is important and saves a lot of effort later on in the 
writing process - even if you are on your own when writing. I do 
so myself when writing bigger/more important documents.


Just my 2 cents!

/Peter Kindström