a really robust "how to get started with YP" document?

a really robust "how to get started with YP" document?

[Robert P. J. Day]

  yes, there's a "getting started" page or two, but i was perusing the
docs recently, and was reminded of the "stuff i wish i'd known" page:

  https://docs.yoctoproject.org/what-i-wish-id-known.html

and remember thinking, "what a cool idea," then thought about it a bit
longer and realized i was looking at it the wrong way. if we actually
think we need a page along the lines of "hey, even though you've been
using YP for a while, here's a bunch of stuff we *could* have told you
long ago to make your life easier but we didn't and now you have to go
back and change stuff to take advantage of it," well, maybe we didn't
prepare people properly in the first place.

  i'm thinking of a really robust, complete, industrial-grade
introduction to YP that lays out *everything* a new user should know
if they're about to immerse themselves. i don't mean, "hey, i want to
build a project to play around," i mean, "hey, i'm about to spend the
next two years on a YP contract and i really need to make sure i'm
doing stuff the right way to be as productive as possible."

  one oversight that i always talk about is how to set up your entire
build directory infrastructure. yes, there are lots of ways to do it,
but newcomers just want to be told what seems to work for most
accomplished YP developers so they can set it up and get to work,
confident they won't need to go back and do it all over again.

  here's a really trivial example -- i've had people who've used YP
for at least a couple years say, "wait ... there's a 'site.conf' file
that i could have been putting all this common stuff in all this
time!?!?"

  other things the truly serious developer should know -- how to use
bitbake-layers and oe-pkgdata-util. and "bitbake -e".

  anyway, you get the idea ... the idea that we think there's value in
a "stuff you wish you had known" page sort of implicitly admits that
we somehow failed to tell them about it in the first place.

  thoughts?

rday

Re: [docs] a really robust "how to get started with YP" document?

[Nicolas Dechesne]

[-- Attachment #1: Type: text/plain, Size: 2325 bytes --]

On Tue, Jun 1, 2021 at 12:34 PM Robert P. J. Day <rpjday@crashcourse.ca>
wrote:

>
>   yes, there's a "getting started" page or two, but i was perusing the
> docs recently, and was reminded of the "stuff i wish i'd known" page:
>
>   https://docs.yoctoproject.org/what-i-wish-id-known.html
>
> and remember thinking, "what a cool idea," then thought about it a bit
> longer and realized i was looking at it the wrong way. if we actually
> think we need a page along the lines of "hey, even though you've been
> using YP for a while, here's a bunch of stuff we *could* have told you
> long ago to make your life easier but we didn't and now you have to go
> back and change stuff to take advantage of it," well, maybe we didn't
> prepare people properly in the first place.
>
>   i'm thinking of a really robust, complete, industrial-grade
> introduction to YP that lays out *everything* a new user should know
> if they're about to immerse themselves. i don't mean, "hey, i want to
> build a project to play around," i mean, "hey, i'm about to spend the
> next two years on a YP contract and i really need to make sure i'm
> doing stuff the right way to be as productive as possible."
>
>   one oversight that i always talk about is how to set up your entire
> build directory infrastructure. yes, there are lots of ways to do it,
> but newcomers just want to be told what seems to work for most
> accomplished YP developers so they can set it up and get to work,
> confident they won't need to go back and do it all over again.
>
>   here's a really trivial example -- i've had people who've used YP
> for at least a couple years say, "wait ... there's a 'site.conf' file
> that i could have been putting all this common stuff in all this
> time!?!?"
>
>   other things the truly serious developer should know -- how to use
> bitbake-layers and oe-pkgdata-util. and "bitbake -e".
>
>   anyway, you get the idea ... the idea that we think there's value in
> a "stuff you wish you had known" page sort of implicitly admits that
> we somehow failed to tell them about it in the first place.
>

Have you checked:
https://docs.yoctoproject.org/brief-yoctoprojectqs/index.html

Should we not try to improve this existing document instead?

>
>   thoughts?
>
> rday
>
> 
>
>

[-- Attachment #2: Type: text/html, Size: 3272 bytes --]

Re: [docs] a really robust "how to get started with YP" document?

[Robert P. J. Day]

[-- Attachment #1: Type: text/plain, Size: 842 bytes --]

On Tue, 1 Jun 2021, Nicolas Dechesne wrote:

... snip ...

> Have you checked:
> https://docs.yoctoproject.org/brief-yoctoprojectqs/index.html
>
> Should we not try to improve this existing document instead?  

  oh, i'm aware of that page, i still don't think it matches what i'm
talking about. i'd make one distinction, and that's between what
someone *must* do to use YP, as opposed to really good workflow
practice to use after that.

  for example, that page talks about how to make sure you have a
compatible linux distro. well, sure, but you *have* to do that, you
don't have a choice. so i'd try to distinguish between:

  1) initial setup *required* to use YP, as opposed to
  2) subsequent good practice that might take years to learn

i see those as two different topics. i will think more on this.

rday

Re: [docs] a really robust "how to get started with YP" document?

[Michael Opdenacker]

Hi Robert,

On 6/1/21 12:51 PM, Robert P. J. Day wrote:
> On Tue, 1 Jun 2021, Nicolas Dechesne wrote:
>
> ... snip ...
>
>> Have you checked:
>> https://docs.yoctoproject.org/brief-yoctoprojectqs/index.html
>>
>> Should we not try to improve this existing document instead?  
>   oh, i'm aware of that page, i still don't think it matches what i'm
> talking about. i'd make one distinction, and that's between what
> someone *must* do to use YP, as opposed to really good workflow
> practice to use after that.
>
>   for example, that page talks about how to make sure you have a
> compatible linux distro. well, sure, but you *have* to do that, you
> don't have a choice. so i'd try to distinguish between:
>
>   1) initial setup *required* to use YP, as opposed to
>   2) subsequent good practice that might take years to learn
>
> i see those as two different topics. i will think more on this.


I tend to agree with your arguments. Indeed, the very existence of this
"What I wish I’d known about Yocto Project" document is a kind of
acknowledgment that the current documentation is not good enough, all
the more as it's the first document the user is exposed to after the
"Quick Build"  one. It's a bit like warning that what follows won't be
sufficient or at least clear enough.

IMHO, if we keep such a document, I believe it would be better placed
close to the end of the list, with a title such as "What to remember and
best practices". Any, your main point remains valid, we should first
make sure that the main manuals are sufficient.

Thanks for proposing this. I hope we can make progress in this direction.

Cheers,

Michael.

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