I also have a couple of suggestions to (IMHO) improve the situation -
From my own experience sometimes being a bit lazy when it comes to
documenting code, I can sympathise with some people adding more features
to ruby, but not neccessarily documenting them well.
If the documentation isn't good, especially the documentation of a
programming language or its libraries - then that might put some people
off the language. (...which is not a good thing, but also something I
can understand in a way...).
On the other hand, if I code some application in ruby and in the process
find something more about the standard library (say by playing around with
a method in a class I've used - but a method that isn't properly
documented), it's quite likely that I'll find out something which would in
turn be helpful to others -- but generating a patch and submitting it back
is a drag just for "a bit of documentation".
I wonder, wouldn't it be a nice idea to bring three tools together to make
it easier to add documentation to the code?
What I'm thinking about would be to build a wiki that doesn't store
individual wiki pages, but rather generates the wiki pages to be displayed
straight from checked out rdoc; and changes to the wiki page would be
written back into the source and committed back into the source
repository.
The usage scenario would roughly look like this -
- during the setup of the server, the "rdoc-wiki" (or whatever it might
be called) extracts the latest source of a given library / libraries;
indexes the respective rdocs embedded in the sources.
- a users surfs to the site - and gets a display like the standard rdoc
documentation - with the difference that it doesn't read static pages,
but a dynamic view of the sources it has under its control.
- the user selects a method and again gets the same display he is used
to, apart from every method now also having an "edit" button - if the
click on that edit button, he'll get to an input window where the rdoc
can be edited directly.
- once the user submits the edited documentation, the server would check
the file back in.
Obviously, a solution like this needs to take a couple of things into
account -
- do not allow inserting code; just present and edit (rdoc)
documentation.
- have some basic protection measure against "blog"/"wiki" spams.
- it must have some way of dealing with conflicts during the check-in
phase (initially probably just bailing out)
Such a system might then hopefully lure more people to ruby, especially
once we get better and better documentation out of it...
Benedikt
--
Gaudeo te illud de me rogavisse.
|
