[Ffmpeg-cvslog] r8312 - trunk/doc/faq.texi

[Diego Biurrun]

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
effort.

Diego