[TYPO3] Documentation nightmare

[virgil huston]

I cross posted this because this topic needs to be transitioned to the Doc
List after a few days.

Ries,

You break the cycle by implementing an editing step in the process. This is
good for all documentation no matter if a technical writer wrote it or a
core developer or anyone else. The editor takes the draft manual and goes
through it to do a number of things:

1. Make sure it makes sense and has all the steps of procedures, etc.
Rewrite for clarity, add info, change inaccurate info.
2. Makes sure proper graphics are used and identify need for additional
graphics/figures.
3. Make sure the manual is in proper English. Many writers are not native
English speakers and many English native speakers are not good writers.

Editing is time consuming and, like everything else, is hard to get done by
busy people working as volunteers. That is why I don't edit more :-) We also
need to get some of the great German manuals translated into English and
other languages.

I have been talking some with Daniel Brusser and Juergen Egling about how to
get the Doc Team energized and maybe now is the time to get something going.

First, if you are not subscribed to the TYPO3-Doc list, that is where the
discussion should be taking place. Next, take a look at
http://wiki.typo3.org/index.php/Main_Page. This is a great resource that
Daniel has provided and is the place for Doc-Team members to work.

In a day or so, I will post on the wiki some ideas of things that I think
need to be done and invite anyone interested to participate. At this stage,
I think we need to group the existing manuals and identify what needs to be
done to each to bring it up to current standards, then prioritize the work
and find people to volunteer. We also need to identify manuals that are
needed but do not exist and manuals in German that need to be translated
into English.

The other thing that hits a nerve with me is the discussion over paying for
documentation. One thing people don't realize is just how time consuming
writing manuals is. Most people realize that a programmer should be paid,
but people expect the documents to magically appear. As a writer, it doesn't
work that way. I am very interested in how some of the Doc work may be
funded. Some of us are developing our own manual "modules" that we can turn
into a "custom" manual for clients because the off the shelf manuals are
outdated and embarassing to give to clients.

Anyway, I hope this discussion will energize the Doc Team!

Regards,
Virgil


On 3/11/08, ries van Twisk <typo3 at rvt.dds.nl> wrote:
>
> >
> >
> >> Futuristic Template Building - last update: 02.02.2004 15:54
> >
> > This one needs a complete rewrite. It is still valid but some things
> > are obsolete and it is easier to write new from scratch than to fix
> > old one. Probably I should be responsible for it as I support TV now
> > but I have no time for it either :(
> >
> >> Every document I find is ancient, yet there are all these cool new
> >> features mention in the modern releases.  How is a newbe to learn
> >> them?
> >
> > It's open source, mate :( One way to push it is to pay for it but it
> > is obvious that very few people will want to pay for doc updates.
>
>
> The problem for somebody else to write some documentation, and I am
> sure there are many people with these skills, is that they need to
> have a very good understanding how a system works.
> To get a good understanding of how things work, these people need to
> get in contact with the people who wrote the code. And since these
> people are often so buzy, it's hard to get information from the people
> who wrote the code so the people who want to write.. cannot write
> because they don't understand it well enough... this seems to be a
> circle....
>
> Question for all of us, how can we break this circle??
>
> Ries
>
>
>
>
>
>
> Ries van Twisk
> tags: Freelance TYPO3 JBoss JasperReports Flex Blaze-DS WebORB
> PostgreSQL DB-Architect
> email: ries at vantwisk.nl
> web:   http://www.rvantwisk.nl/
> skype: callto://r.vantwisk
> Phone: + 1 810-476-4193
>
> _______________________________________________
> TYPO3-english mailing list
> TYPO3-english at lists.netfielders.de
> http://lists.netfielders.de/cgi-bin/mailman/listinfo/typo3-english
>