Yocto Doc Thoughts

Yocto Doc Thoughts

[yates]

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

Hello All,

I was asked to provide my feedback on the Yocto documentation on the #yocto
irc channel a few weeks ago, so here goes. Sorry it’s taken me so long to
get around to it.

First I want to say thank you to all who have volunteered their time to
create the Yocto documentation. The documentation has improved
significantly over the past few years I’ve been using Yocto (since about
2016). The sheer amount and number of documents means this was/is a
Herculean task, even for a large group of volunteers such as yourselves.

Also let me say (as will become obvious) that these ideas are not on
specific problems but address general attributes of the documentation that
I feel could be improved.

OK, so the feedback:

   1.

   Be less flowery. Many of the docs seem to be written with more words
   than are necessary, as if embedding the information in some amount of
   niceties helps engage the reader. In my opinion, it hurts. The overriding
   goal of documentation should be to state things as precisely and succinctly
   as possible so that the reader gets to their information quickly and
   clearly. The writer should spend x amount of time once writing things
   well so that 100,000 users don’t have to spend 100,000⁢x hours.
   2.

   Related to the previous point, factor the information into logical
   pieces and define things once. It seems that many parts of the Yocto
   system are described across several documents. This makes it difficult to
   digest.
   3.

   Be less grammatically and/or syntactically ambiguous, and provide
   sufficient context.

I should have taken some time to provide specific examples, but this is a
start. If it doesn’t irritate folks too much, I can put together a followup
with specifics.

[image: image.png] Randy Yates <:yates@ieee.org>
919-412-8994 (cell, personal)
919-577-9882 (landline, personal)
Generated on Sat Jun 19 01:10:58 2021 by LaTeXML [image: image.png]
<http://dlmf.nist.gov/LaTeXML/>

[-- Attachment #1.2: Type: text/html, Size: 4103 bytes --]

[-- Attachment #2: image.png --]
[-- Type: image/png, Size: 38197 bytes --]

[-- Attachment #3: image.png --]
[-- Type: image/png, Size: 643 bytes --]

Re: [docs] Yocto Doc Thoughts

[Michael Opdenacker]

Hi Randy,

Many thanks about your feedback about our documentation! See my comments
below...

On 6/19/21 7:30 AM, Randy Yates wrote:
>
> Hello All,
>
> I was asked to provide my feedback on the Yocto documentation on the
> #yocto irc channel a few weeks ago, so here goes. Sorry it’s taken me
> so long to get around to it.
>
> First I want to say thank you to all who have volunteered their time
> to create the Yocto documentation. The documentation has improved
> significantly over the past few years I’ve been using Yocto (since
> about 2016). The sheer amount and number of documents means this
> was/is a Herculean task, even for a large group of volunteers such as
> yourselves.
>
> Also let me say (as will become obvious) that these ideas are not on
> specific problems but address general attributes of the documentation
> that I feel could be improved.
>
> OK, so the feedback:
>
> 1.
>
>     Be less flowery. Many of the docs seem to be written with more
>     words than are necessary, as if embedding the information in some
>     amount of niceties helps engage the reader. In my opinion, it
>     hurts. The overriding goal of documentation should be to state
>     things as precisely and succinctly as possible so that the reader
>     gets to their information quickly and clearly. The writer should
>     spend x amount of time once writing things well so that 100,000
>     users don’t have to spend 100,000⁢x hours.
>

I agree with this. As the new (part-time) maintainer of the
documentation, I had that impression too and found redundant
explanations or types of sentences that would be worth factorizing, not
mentioning the style that is definitely worth simplifying too. I already
started some "simple" simplifications, but there is a long way to go.

> 1.
>
>     Related to the previous point, factor the information into logical
>     pieces and define things once. It seems that many parts of the
>     Yocto system are described across several documents. This makes it
>     difficult to digest.
>

Agreed too. The current documentation can definitely be made simpler and
easier to follow, and therefore less time consuming for readers.

> 1.
>
>     Be less grammatically and/or syntactically ambiguous, and provide
>     sufficient context.
>
> I should have taken some time to provide specific examples, but this
> is a start. If it doesn’t irritate folks too much, I can put together
> a followup with specifics.
>
I'd definitely be interested in examples, indeed.

All this is only my opinion, and I'm not the only one in charge (the
community of developers we submit documentation patches to ultimately
decides), but it's good to know that our views intersect.

Thanks again for your contribution.

Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [docs] Yocto Doc Thoughts

[Michael Opdenacker]

Hi Randy,

On 6/21/21 6:55 PM, Michael Opdenacker wrote:
> On 6/19/21 7:30 AM, Randy Yates wrote:
>
>> 1.
>>
>>     Be less grammatically and/or syntactically ambiguous, and provide
>>     sufficient context.
>>
>> I should have taken some time to provide specific examples, but this
>> is a start. If it doesn’t irritate folks too much, I can put together
>> a followup with specifics.
>>
> I'd definitely be interested in examples, indeed.
>
> All this is only my opinion, and I'm not the only one in charge (the
> community of developers we submit documentation patches to ultimately
> decides), but it's good to know that our views intersect.
>
> Thanks again for your contribution.


I'm still interested in the specific examples you were thinking about.
Since working on documentation has to be an iterative process (that's
how the community works!), such examples could be a good starting point.

Thanks in advance,

Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com