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

[Martin Holtz]

Hi François,

> 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
+1 :)

>>> 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.
ok, so i am fine with "beginners and advanced users"

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

>> 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.
i totally aggree

>> 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.
ok, you are right.

>>> * 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.
ok, it sounds for me like "we are the admins of the wiki".  But i am
fine with your version.

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

>>> * 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.
fine!

>>> * 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 ;-)
yep:)

Now, i understand better your focus and i think you are right with it.
So IMHO a +1 for you initial mission statement with "encorage" instead
of "provide/create" at some points:)

Thanks a lot,

gruss,
martin
-- 
Martin Holtz - elemente websolutions http://www.elemente-websolutions.ms

http://wiki.typo3.org/Ts45min - TypoScript in "45" minutes
http://wiki.typo3.org/De:ts45min - (auch in Deutsch)