[Mageia-discuss] [Doc Team] Proposal, questions ?

[John]

On Wed, 6 Oct 2010 07:55:31 +0200
yvan munoz wrote:

> Please first excuse my english level (and sometimes usage of automatic
> translation)
> I have some reflexions and questions i think it could be interesting to
> share here :
> 
> Doc Team.
> 
> _ base : that the documentary team has previously conducted
> _ base : operation for common tools for this job
> 
> _ objective : make participation easy
> _ objective : produce quality docs for readers
> 
> _ question : could we mix the usage of wiki and edition ? ;-)
> _ proposition : reserve wiki for contributors works, simply by have a
> large banner at the top of wiki welcome page (docs.mageia.org ? or
> whereever). Banner invite to download latest doc compil.
> 
> _ effect : no invitation to read wiki. Wiki is ever a working place (as
> cauldron is dev sys)
> _ effect : Readers and users have ever a validated and finalised
> documentation
> _ effect : preserve 'works-ever' wiki and prevent any 'never-finished'
> impression for docs readers
> _ effect : make people want to participate by producing a good doc final
> quality
> 
> No revolution, no new tool, no great idea (sorry :p), just a little orga
> adjusment to change perception of readers on our doc.
> Additonnals : produce in well know format, standard, with easy scanning
> and indexing for desktop tools (as strigi / nepomuk)
> 
> Resume in two sentences :
> Wiki is for workers. Final doc is for readers, and could include common
> texts (as releases notes, issues and wiki doc)
> Mix wiki usage for edition objective to have separation between places :
> works and reads.
> 
> Regards

Historically, in the Mandrake/Mandriva context, documentation was
basically a two-part scheme. Those parts were:

Man pages: Mostly the responsibility of the developers of the applications.

Printed Manuals: Primarily for inclusion in boxed sets for each release,
but included in the distributed media as HTML and PDF files. The manuals
were coordinated by company employees and an international team of writers,
translators, technical and language proofreaders. 

Later, (about 2006 I think) some material (in the form of HowTos) began to
be published as webpages but was not dealt with by the DocTeam itself.

The source material was stored in CVS/SVN repositories on the company
servers using a custom-built application called Borges to manage
synchronisation between each module it's screenshots and the various
language teams.

All base material was written using US English and then translated to each
of the other reference languages. For example the 2008.1 release had 14
'official' languages, each language being coordinated by it's own team
leader.

In my opinion, this scheme worked very well, even if there were a few
'hassles' close to release when some functions in some programs didn't
always work as described :-) (Blame the devs for changing their minds!)

Take a look here to see how the project was organised for 2007.1:

http://wiki.mandriva.com/en/Documentation_Project_Status

At this time I doubt that we would be producing hardcopy manuals but
whatever documentation we produce should be of the same or better quality
as those we produced then. That is; we should aim to use quality writing
and screenshots and regardless of anything else what is produced it should
be in a print-ready form for ease of reference.

Thoughts?

John NZ