[Typo3-doc] Problems around the writing process

[Sylvain Viart]

Hi,

I didn't receive that mail from the ML. :-(
I will reply shortly.

Jean-Marie Schweizer wrote:

> I met Robert Lemke the other day and we had a discussion about the 
> documentation matrix on typo3.org, the wiki and how the docTeam could help.
> 
> Of course, this is again based on my impression, that we haven't really 
> aknowledged the bases of the problems yet, espcially in terms of 
> teamwork with developers and what the community wants/needs.
> 
> If you are tired of me coming back to the same old issue, just don't 
> read any further. If you want me to stop, make a decision or vote me off 
> the team. That would safe us all a lot of time.
> 
> Here it goes:
> 
> [Why Wiki]
> 
> As you all know I was a big supporter of the Wiki from the start, since 
> I could see a huge improvement in teamwork compared to the 
> hard-to-access way with OOo over the online repository, if you want to 
> work as a team.
> 
> [Wiki to SXW]
> 
> The obvious problem with Wiki is: How do we get the content back to the 
> docMatrix (on typo3.org). Robert Lemke programmed a parser that allows 
> browsing an Ooo doc on the fly. And the conversion to a PDF is not a 
> problem at all. So it's natural that anything that is created in the 
> Wiki should be converted OOo to be put on the docMatrix.
> 
> Apparently such a converter is not easy to write and time consumming. So 
> far there hasn't been anyone who stepped forward to provide such a tool. 
> I can understand that since as long as it is not clear if the Wiki will 
> survive as a docTeamWritingTool why bother spending time.
> 
> 
> [Workflow]
> 
> In the discussion with Robert we asked ourselves what could be  an ideal 
> workflow between a programmer and a docTeam writer. This, of course, 
> would cover new documentation or outdated ones, that have to be rewritten.
> 
> The goal would be that the programmer would document just as far as 
> necessary, so that somebody from the docTeam can pick it up from where 
> he stops and put it in the right structure, set it up with the right 
> design rules etc. That way he gains time to put into more programming.
> 
> [Video to documentation]
> 
> One way to do this could be that the programmer  creates a video 
> presenting his extension etc.
> 
> Advantage: He doesn't have to write. He doesn't have to bother about 
> writing rules or formats etc. Screenschots would be instantly available. 
> The docTeam writer just has to transcribe from the Video nput it in the 
> appropriate format.
> 
> At the same time we'd have a video ready to download.
> 
> There are many documentations (although they would be more something 
> like a tutorial) that could be created or updated that way.
> 
> [Proposal]
> 
> Let's think about that possibility and see if it would be worth 
> considering for future development.
> 
> *****************************************************
> 
> [Structure]
> 
> I think most of us agree that the docMatrix structure is not ideal and 
> we need another one. A lot of work has been put in such a structe but 
> none of the proposed ones have lasted long.
> 
> I'm not sure if anyone has tried take what we have in the docMatrix and 
> put it in one big document and restructer if from that point of vies. I 
> can't see that in the current structure or any of the onesthat were 
> proposed.
> 
> But as long as we don't have a good alternativ to the docMatrix the 
> community will rely on the docMatrix rather than the Wiki.
> 
> Maybe it's worth structuring the docMatrix first (and only the 
> docMatrix) before do anything else.
> 
> [Outdated]
> 
> A lot of documentations seem to be outdated, if we consider those 
> documentations outdated that rely on versions like 3.5 etc although 
> there hasn't bee much of a change.
> 
> There will be a need of keeping information relying on subjects to 
> change as little as possible. And those parts of a documentation have to 
> be monitored, meaning they have to be known as subject to change.
> 
> That way we avoid updating documentations when there is not a real need 
> for it to be updated expect for a first time reader who gets confused 
> when we write about 3.5 and the only thing he can download is 3.7.
> 
> [Design]
> 
> Design is defently an issue worth contemplating. Sylvain already talked 
> about the TSRef table structure that could need some improvements etc.
> 
> Similar to the CSS for the Wiki we need Style Templates for the 
> documentations. In this case I would try to work together with the 
> design team and see if one or more typographers can set up design rules 
> for documentations.
> 
> This would include all the writing rules, eg when bold or italic, how to 
> show a user entry etc.
> 
> [Writing Tool]
> 
> We have to find a consense on the writing tool. Are we really sure that 
> Wiki is the way to go? Aren't there any better tools that allow teamwork 
> and already have a converter for SXW.
> 
> Or are we ready to drop the docMatrix and replace it with the Wiki?
> 
> As long as we have to teams, one for the Wiki the other one for the 
> docMatrix we won't come far.
> 
> I do believe though that if we have a good structure for the docMatrix 
> and the whole thing is available on the Wiki we won't have a hard time 
> to find somebody who writes a conversion tool for Wiki2SXW and Wiki2PDF.
> 
> [Translation]
> 
> I have to say that the recent development about translating documents is 
> worrying me. I don't thinks it's wise a this point to focus on anything 
> but english, till we are set and structured and ready to translated 
> (which is far away from now).
> 
> I fear that a lot of work that is done will not last long and be a waste 
> of time where it could be put into building the foundation of an 
> everlasting documentation process concept.
> 
> I don't mean to disrespect the enthusiasm of all those people willing to 
> give what they can but from personal experience having worked in a 
> translation team before I consider this development as too early.
> 
> I rather have anyone who is willing to give to reconsider doing 
> something else for the moment till translation will be able to be made 
> or put him/her on hold.
> 
> 
> [Rules]
> 
> We should reconsider putting down some ground rules (apart from the ones 
> discussed above). We waste a lot of time discussing about what tool we 
> are supposed to use etc. This is mainly because we don't have a clear 
> workflow yet and don't really know if the current tools are going to 
> work etc.
> 
> Also, working with OOo or not depends on the fact if we'll have a better 
> alternative. Up till then we would have to settle for OOo and that's it. 
> Wiki is not, lacking of the conversion Wiki2SXW and the missing build of 
> the docMatrix on the Wiki, an alternative yet.
> 
> So why not put down simple rules that are clear to anyone like:
> 
> - The docTeam format of choice: SXW from OOo.
> - If you work in another programm make sure to convert it to SXW 
> honoring the design rules.
> - etc.
> 
> 
> [Closing words]
> 
> I don't have the time and strenght to write everthing in detail but I 
> hope you get an idea of what my thoughts are.
> 
> I would appreciate if we could work closer together with the developers 
> and that we get Wiki or anything else to a point where we could start 
> writing.
> 
> I'm open to thoughts and impression but please, let's not start a 
> distructive discussion again (for those who like things like that - 
> please read the posts from the beginning of August).
> 
> Jean-Marie


-- 
Regards,
Sylvain Viart -- TYPO3 DocTEAM.