Suggestions to the Ruby community

ruby-talk
1

John said:

One new possibility is wiki.

I suggest people decide on a man style format.
Even if it is not compleltely standard from the start
it will evolve. Finally, all documentation be put on
a wiki with version control. Anybody can modify
or annotate the docs and after some time
a people wishing to earn a reputation as
a writer can review the history of documentation
changes and evolve the documentaton
to the next level.

[snip]

I would encourage not using a Wiki - for these reasons:

  • Requires yet another password, login, signup, address, name, …
  • Can’t be downloaded and set up like HTML pages (like the ruby-man and ruby-ref, which are wonderful!)
  • Can’t be printed out for hard copy
  • Can’t be used offline

However, rdoc and rtool can both be used offline and can create documentation suitable for offline use; same goes for man pages.

For general documentation, why not use DocTool?

David Douthitt
CUNA & Affiliates
UNIX Systems Administrator
ddouthitt@cuna.coop

2

“David Douthitt” DDouthitt@cuna.coop writes:

I would encourage not using a Wiki - for these reasons:

Although I agree that wikis are not the best medium for
documentation…

  • Requires yet another password, login, signup, address, name, …

The RubyGarden wiki is open to all with no access control.

  • Can’t be downloaded and set up like HTML pages (like the ruby-man
    and ruby-ref, which are wonderful!)

That would be trivial to set up (and I’m guessing that wget would
probably already handle it, although you’d have to ignore the ‘Edit’
link)

  • Can’t be printed out for hard copy

True