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

Mark Brown
2020-06-12T10:58:16Z

[-- Attachment #1.1: Type: text/plain, Size: 1301 bytes --]

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.

[-- Attachment #1.2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

[-- Attachment #2: Type: text/plain, Size: 186 bytes --]