[FFmpeg-devel] [VOTE] 1st/3rd person doxy

[Benoit Fouet]

On Fri, 09 Jul 2010 11:36:00 +0100 M?ns Rullg?rd wrote:
> Benoit Fouet <benoit.fouet at free.fr> writes:
> 
> > Hi,
> >
> > On Fri, 09 Jul 2010 10:47:31 +0100 M?ns Rullg?rd wrote:
> >> Rob <robert.swain at gmail.com> writes:
> >> 
> >> > 2010/7/9 M?ns Rullg?rd <mans at mansr.com>:
> >> >> Mike Melanson <mike at multimedia.cx> writes:
> >> >>
> >> >>> What's wrong with the de facto policy of everyone adds documentation
> >> >>> as best they can and the native speakers clean it up after the fact?
> >> >>
> >> >> What a wonderful idea.
> >> >
> >> > I think we have some non-native speakers amongst us who are very good
> >> > at English, better even than a lot of native speakers.
> >> 
> >> So s/native/proficient/.
> >> 
> >> > My stance on documentation is that I don't really care if it's
> >> > perfect, or perfectly consistent. If it's comprehensible then it's
> >> > good. If people want to make it perfect and perfectly consistent,
> >> > fine.
> >> 
> >> Incorrect grammar is hard to parse and detracts from the meaning of
> >> the statement.  Anyone who wants to improve the English form of
> >> the documentation should be encouraged to do so.
> >
> > As Stefano already stated, this is not (really) a grammar problem.
> 
> I've noticed some pretty horribly grammar while looking at the
> documentation.  For example, that bit with the comma Diego removed is
> impossible to make sense of unless you wrote the code.
> 

Sorry for my poor choice of quoting. I only meant that for the topic of
this pole.
And I totally agree that bad grammar should be fixed. The point is that
it often needs to be discussed with whoever wrote the documentation in
the first place, in order to know what (s)he meant.
And as a non-native speaker, I *really* prefer grammatically correct
documentation, as it is much easier to parse when you're not the
original author (or even when you are and you come back to it some time
after writing it).

I hope my position is clearer now.

Ben