AW: [emacs-wiki-discuss] Planner documentation

[Helge Kosuch]

Hello again!

Martin wrote:
> What do you think? I don't want to start something everybody 
> feels superfluous or the wrong approach.

I am very happy that you want to write documentation! I am just starting
with planner, thus it will be very helpful for me.

Now let's go for some arguments:

** Documentation in a wiki **

- When the documentation is done in the wiki, it will be usable for
everybody much earlier. A wiki decreases the probability of failed
documentation projects, which postpone the release date on and on.

- Planner is still evolving quite fast afaik. Therefore, it will be hard to
keep documentation current. Out-dated documentation is a pain. Therefore,
the speed of a wiki is very valuable.

- I am just starting with planner and usually I write down notes for myself
when I learn something. However, when there's a wiki for the topic I usually
write down my hints and insights not only for me but also in the wiki for
everybody. (For other fools the hints of a fool, who has struggled through
something earlier, may be quite valuable.)

- I feel that a wiki is perfectly aligned with the spirit of collaborative
distributed open-source development.

> Disadvantage: Can't be included in the tarball and is not 
> accessible offline. 

On that, you write:
> 2) Write a html-file (e.g. as a transformed wiki page).

Including an html image of the wiki into the tarball is offline accessible.
Moreover, we can enjoy all the good points of a wiki stated above. In
addition, people are online quite often nowadays and have documentation that
is more current in the wiki then.

> 3) Write an info manual

It would be very handy to have it as an info manual. However, I would
propose to do it in the spirit of extreme programming: Do the most important
feature first. In this case, imho this means to produce any concise
documentation in the most easy to handle fashion. I feel that it is better
to convert it to an info manual in a second step later on, including the
contributions of everybody in the wiki.

I am already looking forward impatiently for anything you publish!

:) Helge