Re: [Ksummit-discuss] [TECH TOPIC] Documentation

Mark Brown <[email protected]> Fri, 12 Jun 2020 11:58:09 +0100

Newsgroups	org.linuxfoundation.lists.ksummit-discuss,dev.linux.lists.ksummit
Message-ID	<[email protected]>

On Fri, Jun 12, 2020 at 12:19:39PM +0300, Mike Rapoport wrote:
> On Fri, Jun 12, 2020 at 11:18:52AM +0300, Laurent Pinchart wrote:

> > This would however leave some developers in an uncomfortable situation.
> > While writing documentation is no fun for most of us, it gets much worse
> > for developers who are less fluent in English. Learning how to write
> > good documentation is hard enough without having to also learn a new
> > language. I think this is a problem that needs to be addressed on its
> > own.

> I think we should make a distinction between adding new documentation
> and updating the existing one. I agree that writing documentation is not
> easy, especially when you need to write it from scratch. But making
> small amends to the existing documentation along with the code changes
> so that docs and code would still much is not that difficult. 
> For such cases a request to have documentation update as a part of the
> changes wouldn't be too much to ask.

I wouldn't underestimate the barriers this can create for developers who
are less fluent in English, take a browse through changelogs sometime.
There's a big jump from being able to write understandable code and
communicate what it's about to being able to write clear and useful
documentation.

_______________________________________________
Ksummit-discuss mailing list
[email protected]
https://lists.linuxfoundation.org/mailman/listinfo/ksummit-discuss

signature.asc (application/pgp-signature, 488 B)