From: JamesBritt Date: 2002-09-05T08:29:35+09:00 Subject: RE: suggestions to the Ruby community > -----Original Message----- > From: bbense+comp.lang.ruby.Sep.04.02@telemark.stanford.edu > [mailto:bbense+comp.lang.ruby.Sep.04.02@telemark.stanford.edu] > Sent: Wednesday, September 04, 2002 12:25 PM > To: ruby-talk ML > Subject: Re: suggestions to the Ruby community > > JamesBritt wrote: > >Still, hasn't the Perl experience shown that bundling > documentation with the > >code distribution is a good idea? Does every language have to go through > >the same evolutionary steps? Can't we have a bit of Lamarckianism? > > > > - - I think it's a good idea, particularly in a language as > readable as Ruby. I'm just trying to introduce a bit of scale > into the problem. As I see it, there are a lot of people > complaining and very few doing. I don't see people complaining, I see people questioning, or raising concerns, or thinking out loud, or any number of things. I don't think you intended to be pejorative, but it is not uncommon on this and other lists for some people to label certain discussions as "complaining", or "bickering", or "whining", with the result of discouraging people from speaking up. ("Complaining", "bickering", etc. seem to be defined as "prolonged discussion on something one has now decided to stop considering.") It is entirely possible to see a problem but not have a solution, yet some prefer that nobody speak up unless they can propose an alternative. (And then, when they do, they are told that they should go implement it since they thought of it.) OK, end of rant. There are some discussions that, ultimately, do not have a software solution. They deal more with the underlying principles and philosophy of the community. They may not converge on a solution in one or two days. Matters of documentation may fall into that category. Code runs whether you have comments or not, so who cares, right? What constitutes "appropriate" documentation is quite subjective. "Official" documentation standards or not, what will ultimately drive the creation and maintenance of good, useful documentation are community values. > It won't just happen > overnight. Standards are nice, but usable standards require > a tremendous amount of work. > > To continue your biology metaphor > > "ontogeny recapitulates phylogeny" > > Every language needs to go through the stages, it's just a > question of how fast. I think Ruby could go through this > stage fairly quickly, but I don't expect to see a standard > document format until at least a year after raa.succ ( whatever > that turns out to be ) is well in place. I mentioned Lamarckianism because I view the biology metaphor as deeply suspect. Some people seem to take it on faith that language development must follow some Darwinian, evolutionary processes, but we are not dealing with biology. We have the advantage of extreme hindsight, and the divine ability to manipulate things at will. Every language need not go through the same stages. Conceivably, Matz could just mandate some feature that dictated the path of Ruby documention. This is unlikley, but ultimately there needs to be an explicit guiding hand. Relying on some sort of marketplace of competing formats, styles, and philosophies of documentation, wherein most of the mistakes of the past are repeated, before electing a format, seems needlessly expensive. There is another thread right now concerning Java and Ruby, and while I don't greatly care for Sun or Java, Java has a big advantage in that Sun is quite happy to mandate certain features, such as JavaDoc. Its discouraging to think that a standard Ruby API doc format won't occur until a year after some unknown time in the future. Right now, Ruby has RD (a markup language), and RDoc (a tool for extracting and formatting salient code features and comments). RDoc and rdtool should be part of the base distribution. Essential documentation for the core classes should be with the source code, and updated as the source is updated. Docs can be generated whenever a you grab a new release. Minimal documentation should include what the class or module is for, what each method is for, what each method parameter is for. We might look at the Sun's "Requirements for Writing Java API Specifications" (http://java.sun.com/j2se/javadoc/writingapispecs/index.html) as a guideline. We should ask, what's the cost of selecting a possibly sub-optimal API documentation standard now, versus the cost of waiting until one emerges a year after RAA.next, while further adoption of Ruby is dampened by the lack of complete documentation. > > > >Exactly true. Yet there is the idea that one can just post to > ruby-talk as > >a substitute for having clear documentation. Or that leafing through > >multiple books is a good way to find out what some method > parameter is for. > > > > - - Well, that works fine until you reach a certain scale of > use. IMHO, the demand for perl-style documentation is > getting the horse in front of the cart. That scale of use won't happen if people find it too hard to locate complete class and library help. I define "too hard" as having to look in more than one place. Many people have decided they like Ruby, and have stuck with it long enough to figure out all the places to dig when trying to learn the language. Others, though, have walked away because this is just too much of an investment. For the former, the various workarounds adopted in lieu of complete API documentation have become second nature, so that when somebody such as stibbs suggests this is a real problem, people act puzzled. Ruby itself wins over hackers and language fans, but persuading management is a bit harder. (Kent Starr expressed it quite well in [ruby-talk 49040].) > There is a chicken > and egg problem here, once consensus is reached then > most people will fall in line, but people are reluctant > to put much effort into documentation until consensus > is reached. People don't omit documentation because they don't know what style to use; they omit it because they know they will not get any flack. Many of the Java developers I worked with never bothered to write even basic JavaDoc comments, and it wasn't because they were ignorant of JavaDoc. It was because they could wave their hands and tell people "read the source", and people considered that acceptable geek machismo. Later, these same people wondered why management wanted to drop the custom code and go with an off-the-shelf, fully documented product. > >Why isn't documentation considered part of coding? If you write > some code > >you are (or should be), by definition, its documenter. > > - - In practice this almost never works. Writing good code and > writing good documentation are separate skills. Even if you > can write documentation as the code's author, you often have > many things that are "just obvious" that you never even think > to document. That someone isn't as good at writing docs as writing code shouldn't excuse anyone from writing docs. Besides, "skill to do comes from doing." I also agree with Matt Gushee's comments in [ruby-talk 49021]. It would be nice to have the appropriate division of labor, but in the meantime, software developers need to write. > > > > - - In my experience, when you start saying "should" in the open > source world you're generally wasting your time. I don't think > you'll get any real disagreement with the above statement, the > problem is picking the standard. I know, it's sort of like saying, "Somebody should take out the garbage." By and large, open-source software (OSS) developers produce those things they enjoy doing, which often overlaps with those things other people want or need. But it's the gaps and omissions that discredit much OSS in the eyes of many looking for professional-grade tools. There isn't always somebody taking out the garbage. > >But some matters seem as if they should be > >fairly simple to resolve. For example, where does documentation > (in *any* > >format) go if it's not embedded in the code? Can we just agree > that every > >lib distribution has an immediate subdirectory called 'docs', > and avoid the > >'lib/dbi/doc/DBI_SPEC' problem? > > - - These are not "fairly simple to resolve", they are exceedingly > complex and require a lot of community thrashing and > competition between competing ideas/models before consensus > is reached. Standards emerge from the documentation, > documentation does not emerge from standards. I'm not saying > we should not tackle these problems, I'm saying it's a lot > more complicated that most people seem to think. Resolving every aspect of a uniform documentation process may be complex. Where to place the docs in a library distribution is not. James > > - - Booker C. Bense