[Typo3-documentation] Previous message #4 (was: Fwd: Re: Help with Installation documentation?)

[Michael Stucki]

Subject: Re: Help with Installation documentation?
Date: Sonntag, 13. Juni 2004 19.46
From: "Peter Kindström" <peter.kindstrom at abc.se>
To: Michael Stucki <mundaun at gmx.ch>

Hi Michael

> sorry for letting you wait so long. I already received your mail
> from April 21 but didn't reply ever yet.

Its okay! I saw that Kasper released the new version of the
install manual just after my last email and then I thougth an
answer was not necessary...

> > I would like to help with structuring and "unifying" the
> > installation documentation a bit.
>
> Right. I have looked at your documents (I had the link from your
> first mail) at http://www.infolagret.se/index.php?id=18.
>
> Mostly, I'm with you. I already discussed the topic with Kasper
> and share some of his thoughts as well (see attached mail).
>
> If you could improve the "Installation & Upgrade" manual
> according to your needs, that would be great. If you think
> there's no chance to continue working on that document and start
> with new ones, let's discuss this here.

Before thinking of improvement, I think it should be devided
into two (maybe three) different documents. Mainly because when
you install, you dont need the upgrade part and vice versa...

Maybe it is also easier to maintain two documents... I think the
possibility to get someone to maintain a 10 page document is
_slightly_ bigger than having someone to maintain one 100 page
document...? But on the other hand there will be more 10 page
documents.  :-)

I also believe that if every document just cover _one_ topic
(say installation) it will be easier for users to find just the
document he/she needs - IF all the documentation are well
structured/categorised...

But maybe this discussion belongs to the Roadmap team? Or who is
really in charge of the overall structure and categories?

> > And with this as a start I like to try getting configuration
> > information out of the install/upgrade documentation and form a
> > new line of configuration documentation, like:
> >  * TYPO3 Configuration Basics
> >  * TYPO3 PHP Configuration
> >  * TYPO3 Basic Templates
> >  * TYPO3 Advanced Templates
> >  * TYPO3 TypoScript By Example
>
> Would be great if we had this, but it's a huge task! I don't
> think it's realistic that this will ever be done,

Hmmm, I think that much of this information already exist - in
different tutorials and the installation guide (PHP config)!

But my point is that we should have a separate category about
configuring Typo3 and with a clean-structured series like you
suggested on Installation documents. I believe we should not mix
installation, upgrade and configuration in the same document.

Then when we know how we wish things to be, we can focus on
getting it that way (which probably is a huge task, as you say).

> In my opinion, it would be a great step if we only had a
> clean-structured series of installation manuals (see above) where
> the main document should include all important information while
> the distribution specific ones extend this one and include some
> deeper information).
>
> What do you think?

I agree. Two documents with basic/general information and useful
for must users. Then "a bunch" of extra documents covering
different special situations...

> > I like to get a discussion about this idea and out of that
> > discussion I like to deside if membership in the project is
> > interesting or not (for me and the project). Of course I will
> > get involved in other things than the above mentioned if I
> > decide to join a project!
>
> It's really great that you want to help our project. I would be
> happy if you joined the team!
>
>
> However, please keep in mind that writing documentation seems to
> be a very ungraceful task. Have a look at some of the last topics
> on the Debian list. Everybody will nag about your work but nobody
> will actually help you to improve it. Just be aware of that!

I know! And I am used to it.
I have read some of the postings in the Debian tread and if you
look beneath all the anger, frustration and hard words, you
almost always find that they got a point!

I agree that you should ignore all the hard words, but you
should always read the postings carefully to see what they
_really_ is saying - like "it would be nice if someone tried to
write a better Debian install manual"...  ;-)



Regards,
Peter Kindström  <peter.kindstrom at abc.se>