Re: [docs] Yocto Doc Thoughts

["Michael Opdenacker" <michael.opdenacker@bootlin.com>]

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