[oe] Documentation problems

[Paul Menzel]

Am Sonntag, den 27.11.2011, 18:56 +0000 schrieb Paul Eggleton:
> On Sunday 27 November 2011 19:38:39 Paul Menzel wrote:
> > Only Koen brought up the idea of the pull model. By itself, ikiwiki also
> > allows Web edits [1].
> 
> Yes but what benefit do we get by changing the system? Only that the backend 
> changes to git? Given that MediaWiki is familiar to many (thanks to Wikipedia) 
> I would be hesitant to replace it with anything less widely understood.

Everything is in one place. And developers are not familiar with
MediaWiki or most of the time hate it to not be able to use their
favorite editor and to use a Web interface.

Maybe a survey should be held. It is work in the beginning but would pay
back in the end since this infrastructure should be used for a while. Or
we just try it out.

> > Additionally, you have not addressed the point that reality shows, that
> > not a lot of people write documentation and use it. The best way to
> > “enforce” this is to add documentation with the corresponding change.
> 
> I'm not sure I understand what you mean here. If you're suggesting that we 
> will be able to force people to write changes for the documentation together 
> with their changes to the code, I think there are two problems with this: 
>   (1) it assumes that we already have complete documentation for the current 
> state of the code;

Then people could update that part in one go or should at least add a
TODO somewhere.

>   (2) given that writing meaningful commit messages is a challenge for many 
> contributors, you're going to have a very difficult time getting people to write 
> documentation for their changes as well.

That is our choice to make. Either we want good documentation. Then we
have to make this a requirement and contributors have to deal with that
but will get help from the list too. Or we do not enforce this and
probably the documentation will be lacking.


Thanks,

Paul
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 198 bytes
Desc: This is a digitally signed message part
URL: <http://lists.openembedded.org/pipermail/openembedded-devel/attachments/20111127/d9f53f1e/attachment-0002.sig>