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 _______________________________________________ yocto mailing list [email protected] https://lists.yoctoproject.org/listinfo/yocto
