[Ffmpeg-cvslog] r8312 - trunk/doc/faq.texi
Sun Mar 11 17:02:04 CET 2007
On Sun, Mar 11, 2007 at 01:49:13PM +0100, Michael Niedermayer wrote:
> On Sun, Mar 11, 2007 at 11:00:25AM +0000, M?ns Rullg?rd wrote:
> > Michael Niedermayer <michaelni at gmx.at> writes:
> > > On Sat, Mar 10, 2007 at 01:21:41PM +0000, M?ns Rullg?rd wrote:
> > >> diego <subversion at mplayerhq.hu> writes:
> > >>
> > >> > Author: diego
> > >> > Date: Sat Mar 10 14:12:24 2007
> > >> > New Revision: 8312
> > >> >
> > >> > Modified:
> > >> > trunk/doc/faq.texi
> > >> >
> > >> > Log:
> > >> > markup/wording/spelling/formatting improvements for the last commit
> > >
> > > thanks for cleaning my mess up ...
You are welcome.
> > >> Can we make it a rule that any commits to documentation must use
> > >> correct spelling and grammar, at least to the best knowledge of the
> > >> committer?
> > >
> > > iam not happy about such a rule at all ...
> > I was afraid you might not be. Would you care to explain why you
> > think it's OK to write barely understandable English in documentation,
> > but insist on top-notch code? I agree about code quality being
> > important, but I find it odd for someone to be so strict about some
> > things, and yet completely careless about others.
> well lets see
> * IMHO capitalization and punktuation doesnt improve readability, especially
> not in the way in which it is used in normal languages, maybe if we would
> rather capitalize keywords which are important, its rather that most people
> are used to specific things being capitalized and have difficulty if the
> text is not capitalized in the same way ...
Well, you are wrong, completely wrong.
Punctuation increases readability enormously as anybody reading your
period-less prose will be able to certify. Without punctuation it
becomes unnecessarily hard to parse sentences. Telling where a sentence
begins or ends is often ambiguous, which forces one to reread it. Also,
it makes sentences (seem) longer. Long sentences are hard to understand.
> * as i never capitalize & punktuate in a standard conformat way i lack
> practice so dont overestimate my ability to do it correctly if i wanted...
> * additionally iam 99% sure everyone writes docs to their best knowledge
> about spelling, grammer, and such,
Ummm, you don't. You've only recently decided to write all lowercase
and later decided to throw punctuation overboard. I don't mind
lowercase in emails, but lack of punctuation is not excusable IMO.
> sure everyone can read the check the text 3 times and fix everything
> they notice but that costs extra time and turns a hated job into one
> most people wont do at all, few developers like writing docs ...
I don't expect this, neither does Mans. Pressing the '.' on your
keyboard will not cost you significant amounts of time, though.
> * there is no lack of people who can and do fix the spelling&grammer and they
> can within short time produce much more readable text than what the average
> developer can in 5 times more time, its simply that some people are better
> at coding and some better at writing docs, also keep in mind many developers
> are not native english speakers ...
I don't mind cleaning up docs, but if people are purposefully sloppy
this becomes a pain.
Also, the above argument just doesn't cut it. Why not commit sloppy
code then? You can probably fix it 5x faster than the average dev ..
Nobody is expecting wonders, but I believe it's fair to expect a small
More information about the ffmpeg-cvslog