Documentation

[Sebastien Pouliot]

Hello,

Some may have noticed that all rules are now documented on mono-
project wiki. The idea was to have all user documentation in one place
(and the wiki looks better IMHO) and all developer documentation here
(in the Google group).

Now this also cause a small, unanticipated, problem: when do we update
the wiki ?
- when a new rule is created in SVN ? or
- when a new gendarme release is made ?

Since new Gendarme releases will occur about every three months (in
sync with Mono releases) it seems a (too) long time to have new rules
on the wiki (it would be confusing for new users). OTOH I don't want
to wait just prior a release to start the documentation (since even
doing the "tagging" takes quite some time).

My "solution" is to put a copy of the wiki content in SVN. This way we
can continue to add/change/improve documentation between releases and
the update (to the wiki) shouldn't be too hard. The "wiki" files could
even be used to create "user" rule documentation for monodoc (if
someone is looking for a small project ;-)

Anyone has a better/other idea to tackle this ?

Or knows some media-wiki tools to do so ?

Thanks
Sebastien

p.s. I don't see any problem having developer documentation (this
site) updated in sync with SVN. In fact this is probably more useful
this way.

[Andreas Noever]

Hello,

On Feb 6, 2008 3:52 AM, Sebastien Pouliot <sebastie...@gmail.com> wrote:
>
> Hello,
>
> Some may have noticed that all rules are now documented on mono-
> project wiki. The idea was to have all user documentation in one place
> (and the wiki looks better IMHO) and all developer documentation here
> (in the Google group).
>
> Now this also cause a small, unanticipated, problem: when do we update
> the wiki ?
> - when a new rule is created in SVN ? or
> - when a new gendarme release is made ?

I would put the new documentation directly into the wiki. Either on a
new page or annotate them with a red "SVN ONLY" header. If gendarme is
used generate reports for the mono class libraries, up to date rule
documentation will be necessary.

Andreas

[Sebastien Pouliot]

Hello Andreas,

On Feb 6, 10:39 am, "Andreas Noever" <andreas.noe...@gmail.com> wrote:
> Hello,
>

I like the idea. It let us "promote" the upcoming changes and keep a
single source for the documentation.
It also doesn't preclude "scrapping" the mediawiki data to generate
documentation in the future.

Unless there are other ideas I think I'll try this approach (we have 2
rules that are almost ready to be committed) and we'll see how well it
works in "real life"(tm).

Thanks
Sebastien