[TYPO3-UG US] extension manual update

[Dimitri Tarassenko]

Alex,

On 10/15/05, Alex Heizer <alex at tekdevelopment.com> wrote:
> locate documentation. Currently, the (few) reviewed docs are on my hard
> drive. Let's see how quickly we can get them moved! :)

Keep us posted! ;)

> Due to the fact that there are over 1000 extensions (at last rumor) to
> get through, I'm not doing any track changes. Since our job isn't to
> rewrite the manuals, only to "correct" spelling and grammar to be
> acceptable to the US market, changes will mostly be things like
> capitalization, switching transposed letters, smoothing sentences for
> readability, etc.

By "track changes" I was referring to the feature of MS Word which
lets you see what has been changed since the original version. In
OpenOffice (which I presume you used) a similar feature is at
Edit/Changes. OO also lets you save revisions in File/Versions.

Having an easy way to compare the revised version with the original is
very important if you want the extension maintainers to get your
changes approved quickly.

There is always a possibility just to compare two files, but in my
experience, comparing a document created in one version of OO with a
revision of the same document edited and saved in later version may
not always work well.

> 2. Provide a single well-known contact point for extension developers
> and the core doc team to send changes or new English manuals that need
> to be reviewed.

Actually, this is something a "chief translator" of the language is
supposed to be doing. The chief translator of English is Kasper
himself.

> 3. Set up a "merge" system so that new changes can easily be merged with
> already-reviewed docs.

Currently, TER is set up in a way that you either need to go through
the extension contributors to update the documentation, or need to
take the question high enough in the food chain to give you update
access to TER. The second is very unlikely to work out.

> 4. Provide a single well-known contact point so that if anyone notices
> something that needs to be changed, they can contact the doc team
> directly instead of posting to the mailing list/forum.
> and, of course...

That's a tough one. Currently these things typically end up in the
user comments to the documentation. I don't remember seeing anything
like this in Mantis (bugs.typo3.), but then again - there are no
newbies in Mantis and hard core Typo3 hackers are too busy with
hacking the core to pay attention to this stuff ;)))

I would not expect that the model when we react to somebody pointing
out to problematic spots in the documentation would work - accepting
newbie / anonymous feedback and quality management have always been
Typo3's soft spot and nowhere it is as obvious as in quality of
documentation. I think we should be more proactive and that's why what
you do is great!

Thanks!

--
Dimitri Tarassenko