Documentation medium

[Sylvain Hellegouarch]

Hi folks,

As we approach CP2.1 release, we can see that the current wiki is not good
enough for documenting efficently CP. The book we are writing is one answer to
the problem.

But it does not solve the sections that change quite often such as FAQ entries
or Recipes.

I don't feel like the Trac wiki is good for documentation purpose and I also
feel we should have a separate wiki for documentation. The current wiki is
getting really messy and doesn't sell CP well!

I have found a nice wiki page :

http://wiki.splitbrain.org/wiki:compare

Could we have a look at it and maybe have a dedicated wiki for documentation?

- Sylvain



----------------------------------------------------------------
This message was sent using IMP, the Internet Messaging Program.

[Jos Yule]

Sylvain Hellegouarch wrote:

> Could we have a look at it and maybe have a dedicated wiki for documentation?

Whatever the choice is, i really do like using the wiki for some
documentation. I hope we do keep using some kind of wiki tool, in
addition to the more "professional" documentation that is currently
being produced in SVN.

j

--
jos yule
Digital Hyakugei

mailto:j...@theorganization.net
http://www.theorganization.net

jabber:hyak...@jabber.org
msn:hyak...@hotmail.com
yahoo:digital_hyakugei
aim:josyule
icq:295196397

[Peter Hunt]

I don't see what's wrong with a Trac wiki. It just needs some major
cleaning up.

[Sylvain Hellegouarch]

Well I think we should have a separate wiki for documentation at least.

Besides that you just pointed out the problem of a wiki... it needs a major
clean up each time we change something.

Well you could argue that it would go the same for any medium we could use (eg:
a CMS for instance).

My point is that since a wiki doesn't force you in its very nature to follow a
pre-defined structure, we should define our structure and organise it a bit
more.

For instance being able to organise following different CP versions would be a
must have.

- Sylvain

Selon Peter Hunt <floyd...@gmail.com>:

[Jos Yule]

Peter Hunt wrote:
> I don't see what's wrong with a Trac wiki. It just needs some major
> cleaning up.

And some navigation pages, so we can have an entry point for people
looking for pages related to 2.0 and 2.1.

[Jason Huggins]

One random idea I had is that it would be nice if Trac allowed
namespaces in the wiki...

Then you create a new namespace for each version of CP.

Trac is open-source... I wonder how hard it is to hack that in?

-Jason

[Sylvain Hellegouarch]

Hey guys,

I've been checking existing wikis and I think DokuWiki would be better
than Trac for documentation.
http://wiki.splitbrain.org/wiki:dokuwiki

Check the features :
http://wiki.splitbrain.org/wiki%3Afeatures

But some are really interesting in our context :

- Namespaces (which would allow us to divide the wiki in versions)
- Multilanguage support
- Embdedding images
- RSS feed
- read only pages
- syntax highlighting

So I would like to know if you would agree to set up a new wiki
dedicated to the doc project (Recipes, code snippets, etc.)

I really think if we keep Trac it will get more and more messy

- Sylvain

[Remi Delon]

Well, what I had in mind was to completely get rid of Wikis for
documentation, and only have the "official" documentation, which is kept
in the Subversion tree ...

Do you think that's too extreme and a Wiki can still be useful for
*some* things ? Which ones ?


Remi.

[Sylvain Hellegouarch]

> Well, what I had in mind was to completely get rid of Wikis for
> documentation, and only have the "official" documentation, which is
> kept in the Subversion tree ...
>
> Do you think that's too extreme and a Wiki can still be useful for
> *some* things ? Which ones ?
>

Well it might be the easiest way to keep control on all the
documentation that we could offer. But a wiki is also really flexible. I
don't have a definite state of mind on that subject.