[TYPO3-doc] Redefining the missions of the Documentation Team

[François Suter]

Hi Martin,

Thanks a lot for your feedback. Sorry for the long silence, but I was 
busy with old friends for a few days and then was sick for a couple 
more. Now that my brain seems to be running at least at half power, I'm 
trying to answer the various threads.

In general my idea was to try and keep the missions list as a bullet 
list of short items and provide further explanations below. I forgot to 
mention that in my original post, which is really silly. I think what 
should come out of this discussion is:

- a list of short bullet points on which we all agree
- a list of all additional explanations that seem necessary

>> The Documentation Team aims to provide exhaustive, quality documentation
>> about TYPO3 for both beginners and advanced users, with the help of the
>> community. In order to achieve this, it pursues the following goals:
> what are "beginners" and "users"?

What I meant really is "newcomers and regular users". Does that sound 
better?

> Do we take care about editors?

Yes! That's why I would like to stay vague with "users", because there 
are so many sorts. And it's very difficult to define user categories 
that everyone will adhere to.

> If yes, is CSH something we should have in mind?

I think the DocTeam should help with CSH. We should review the CSH from 
the Core and maybe offer guidelines for extension developers on how to 
write their own CSH. That's actually the type of stuff I was thinking 
about in the point "support the TYPO3 Core Team and any other team in 
their documentation efforts".

> Or do we only focus on that people, who install and manage TYPO3
> (admins) or
> writing Extensions (developers)?

We don't. Any aspect of TYPO3 may warrant documentation. Of course this 
doesn't mean that we should feel under pressure to write manuals about 
everything. The missions list states an ideal that we can only fulfill 
to the best of our abilities and available time as volunteers. The whole 
mission statement certainly looks daunting, but it's there to guide us 
in our work, not to depress us because we have achieved only a tiny part.

> And you defined different types of documentation. I think we should
> integrate it here.

I wouldn't. The types of documentation is something that's specific to 
official documentation, which is only one mission of the DocTeam. So I 
think it doesn't belong to here.

>> * provide a tool for the participative creation of documentation
>> (wiki)
> * maintain (and organize?) wiki.typo3.org to have a low entry barrier for
> writing documentation

I prefer my version ;-) Again my aim here is to stay as general as 
possible, because we're talking about a mission statement and not a 
to-do list. The fact that the wiki is a low-entry barrier tool for 
writing documentation, which at some point can get "promoted" to 
official documentation is an internal process, which can be part of the 
expanded explanations.

>> * support the TYPO3 Core Team and any other team in their
>> documentation efforts
> well, what should that mean? IMHO not clear enough

One point was already mentioned above: CSH. I'm also thinking about the 
inline manual, which is desperately obsolete. It could also be writing 
or improving manuals for system extensions. Again I would like to stay 
general, because you never know what else might come up. What I'm trying 
to achieve here is to send a message that the DocTeam can and should 
support the Core Team with matters related to documentation. It can both 
take initiative of its own or respond to requests from the Core Team.

>> * provide on-line tools for easy reference to TYPO3's main languages
>> and APIs
> * maintain on-line tools for easy ...
> i think, it should not be the main task of the documentation team, to
> provide (create) such an tool. Perhaps its an lack of english skills
> on my
> side in this point, but i understand provide that way, that we create
> such
> an tool. It should be ok, if we do it - but it should not be an central
> task. Maintaining such an tool should be an central task.

You're right, "provide" is not the right word here. What I would like to 
express is that the DocTeam could/should be present at many points in 
such projects. It could be the initiator and lead the project. It could 
also come across some valid project and help it along (in a way this 
would be similar to a wiki manual becoming an official manual). It would 
also care for its maintenance.

So what about something like that?

* encourage the creation of on-line tools for easy reference to TYPO3's 
main languages and APIs, ensure quality and maintenance.

>> * create and maintain any other tool which favors documentation and
>> understanding of TYPO3
> the same as above - i am not sure, if creation of tools should be an
> important task of the documentation team. Its ok, if we do it - but it
> should not be a main task of the documentation team to write code.

Definitely same as above ;-)

Again thanks for your extensive feedback.

Cheers

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