On Fri, Nov 25, 2011 at 12:16:31PM +0100, Sébastien Brisard wrote:
> >
> > One more point on this. "Consistency" as some sort of independent goal by
> > itself has no place in open source software. We need to keep our eyes on
> > the prize, which is making it easy for users to understand and use the
> > software and for volunteers to get involved. To the extent that consistent
> > API and doco design contributes to these goals, great. But arcane rules or
> > excessively complicated APIs that make it harder for people to use the
> > software and get involved are to be avoided.
> >
> > Phil
> >
>
> Right. I'm going to grab a shovel and start digging a hole to bury
> myself in right now. For my defence, I remember having been asked to
> conform to those rules I was enumerating in my first post a while ago.
> Whether it was something which had wide consensus was actually my
> question. Sorry Luc and Phil for taking your time.
Well, don't be sorry, as I consider that consistency is an integral part of
a good project.
My view is constantly being misinterpreted: The argument is not on the
contents, which must be complete and accurate, and we all agree on this
_obvious_ truth.
Contents formatting is the _next_ step towards a higher standard of quality.
The Javadoc is a great idea (that documentation could be a nice read). So,
in the same way that you wouldn't buy a badly formatted book (or that
publishers of scientific papers, for instance, enforce consistent
formatting), the quality of documentation of a purposedly public project
should be as high as possible.
Consistency is the opposite of being arcane: it means that the same rules
are applied everywhere. And this ultimately facilitates communication.
I do not care what rules are selected, but I care a lot about consistency.
Quality, on _all_ fronts, should be the common goal.
Why argue about this indeed? Documentation is written once but read many,
many times. Why not capitalize or type the final period (if that's the
rule[1])? The extra effort is minimal compared to the time one would
usually need in order to write good _contents_.
Gilles
[1] As one example, I myself prefer to not put an "s" in a verbal form
(e.g. I'd write "Compute the sum..." instead "Computes the sum...").
I don't do it in my code, but I now do it in everything I write/correct
in CM, because it was the preferred choice here.
As Sébastien, and I before, asked, please state your preferred choices
and please, let's all stick, once and for all, to what the majority
decides.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
