[yocto] All incompassing documentation

[Brian Lloyd]

I took a look at the mega-manual for the first time after hearing
mention of it in the meeting.

>From a new user perspective, it seems a step backwards.  While
everything may be there, it has the needle in the haystack feeling.  The
only way to find something is to search for it, but what search term to
use?  How do you even learn the basic terminology so you are speaking
the same "language" everyone else is?


The individual documents had tables of contents that would let you find
what you were looking for, or at least take a stab at it.  In this
document, it feels hopeless.  For instance, I want to know about
creating new software "Packages" but a search for packages is not at all
helpful.  With no table of contents I cannot use that to narrow down my
search for what is of interest.  Most of my hits for such an item
discuss the packages I will need to install in my host distribution so I
can use the yocto project (not surprised, the danger of a term as vague
as packages).


Another issue I see is that information in the document seems to be more
redundant (seems as separately it was just as redundant just not as
noticeable).  While including the same information in multiple documents
is good when the documents are separated and a user is using just one of
them, when pulling them together like this having an area at the
beginning go over installation (quick start) and then have a later
section go over it again seems a little redundant, and adds a lot more
to search through when trying to find items of interest.

Also on the redundancy issue, when two documents need to cover the same
thing, such as which packages to install in a distro, I suggest a common
source for the section be used that both share.  While having things
worded differently can help have things make sense to more people,
having to look in separate locations for the different ways it is said
isn't a good idea.  So, if both ways of saying it are useful, both
documents probably should have both wordings, and they should be found
together, or at the least one references the other (for more
details/specific steps see Appendix XYZ).  There are exceptions (a quick
start guide for instance), but those exceptions probably should either
be treated like an appendix or not included in this document.




So, areas I'm curious about:
How is the redundancy being reduced, or is it not considered an issue?
What options to help a user find the sections of interest are being
considered, or is search for keywords the way the document is envisioned
to be used?


Interestingly, after not needing to build the documentation from the
sources being mentioned, I ran into this in the documentation:

BitBake: The task executor and scheduler used by the OpenEmbedded build
system to build images. For more information on BitBake, see the BitBake
documentation in the bitbake/doc/manual directory of the Source
Directory.


Which of course I then had to build to read, so seems at least some
documentation is expected to be built from sources.


Hopefully I haven't rambled so much to turn everyone off.  At least one
thing about documentation I haven't mastered is keeping it short...



Brian