9566 2016-05-02 18:23:26 +0000 devtool documentation is duplicated in dev and sdk manuals 2018-03-23 12:02:52 +0000 1 1 9 Documentation Development Manual development 2.1 x86 Multiple RESOLVED FIXED 23 March 2018: RESOLVED Medium+ normal 2.5 M4 1 henry.bruce bluelightning bluelightning henry.bruce kristi sgw srifenbark --- --- Done (doc changes complete) oldest_to_newest 61854 0 henry.bruce 2016-05-02 18:23:26 +0000 In previous releases, devtool was documented in http://www.yoctoproject.org/docs/latest/dev-manual/dev-manual.html#using-devtool-in-your-workflow Now most up to date devtool documentation can be found at http://www.yoctoproject.org/docs/latest/sdk-manual/sdk-manual.html#sdk-extensible As devtool is parts of core build tools and extensible SDK, perhaps it should be documented in a common area and both manuals point to it? It should be made clear to developers that devtool uses recipetool and they should engage with devtool first. If devtool fails to create a working recipe, it may be easier to manually edit that use recipetool. 62674 1 srifenbark 2016-06-06 18:29:07 +0000 Hi, Maybe the section titled "devtool Quick Reference" (http://www.yoctoproject.org/docs/2.2/dev-manual/dev-manual.html#devtool-quick-reference), which is in the dev-manual, should really be moved to somewhere in the YP Reference Manual. The section really is reference material. I feel that "Using devtool in Your Workflow" (http://www.yoctoproject.org/docs/2.2/dev-manual/dev-manual.html#using-devtool-in-your-workflow) is legit for the dev-manual. In the SDK manual, the main section for devtool is "Using devtool in Your SDK Flow" (http://www.yoctoproject.org/docs/2.2/sdk-manual/sdk-manual.html#using-devtool-in-your-sdk-workflow). The flow part here is redundant from what is presented in the dev-manual. I recall some discussion with Paul Eggleton when we were designing the new SDK manual that we purposely repeated this flow stuff. Maybe it is time to rethink that. Also in the SDK manual, there is some elaboration on the devtool add command, "A Closer Look at devtool add" (http://www.yoctoproject.org/docs/2.2/sdk-manual/sdk-manual.html#sdk-a-closer-look-at-devtool-add). I don't know if the information in that section is specific to SDKs or not. If not, I would suggest moving that to the ref-manual along with the "Quick Reference" stuff mentioned earlier. So these are some thoughts here on this bug... I am adding Paul to the list. Scott 62681 2 bluelightning 2016-06-06 20:50:27 +0000 The SDK manual intentionally duplicates the devtool information - the reasoning was to avoid SDK users (who probably won't care about the rest of YP) having to have to refer to other manuals. devtool usage is slightly different within the SDK as well (mostly additional commands) so it isn't simply cut-and-paste. It is true that we put together the SDK manual after the devtool documentation in the dev manual - we should probably review the latter and check to see if we need to enhance it. 62716 3 srifenbark 2016-06-07 17:38:54 +0000 Hi, Specifically, what do you think of moving that devtool reference section from the dev-manual to the ref-manual? That makes sense to me. Thoughts on that? Scott 63356 4 srifenbark 2016-06-27 17:49:23 +0000 Hey, I am not doing anything drastic to these sections until we get some consensus on what we would like. 66511 5 srifenbark 2016-09-22 17:25:16 +0000 Hi, So some stuff has been done on this. We still have devtool stuff in both the sdk-manual and dev-manual. I have moved the devtool quick reference out of the dev-manual and placed it in its own chapter in the ref-manual as it is truly reference material. I have swapped the order of appearance for the standard SDK and the extensible SDK so that we are emphasizing the extensible SDK now rather than the standard SDK. We still have duplicated text regarding the add, modify, and upgrade flows for devtool that appear in both the sdk-manual and the dev-manual. It appears possible to single source this information but I am not going to attempt that during the 2.2 release. I will look again at that post 2.2. Scott 66897 6 bluelightning 2016-10-04 20:06:01 +0000 I'm going to assign this back to Scott since it's a documentation internal structure issue now. 66943 7 srifenbark 2016-10-05 15:19:50 +0000 Setting to IN PROGRESS DESIGN as I need to figure this one out. Scott 70768 8 srifenbark 2017-02-16 19:25:15 +0000 Pushing this to 2.3 M4. I need other's input. Setting to NEEDINFO scott 71408 9 henry.bruce 2017-03-17 17:56:29 +0000 Henry to ping Paul and get back to Scott. 71724 10 henry.bruce 2017-03-24 18:29:59 +0000 I recommend that devtool commands and procedures common to the both the bitbake and eSDk environment are covered in the dev manual and esdk-only commands covered in the sdk manual. 71968 11 sjolley.yp.pm 2017-03-31 15:46:10 +0000 It appears Henry has answered the question. 72112 12 henry.bruce 2017-04-05 21:58:24 +0000 I just spoke to Paul and he is keen to keep to two separate entries for devtool in case eSDK users get lost in the dev manual and try and use bitbake. Scott's reluctance to maintain the same info in two places is a reasonable concern. Perhaps use of docbook include functionality might help here? I'll try and set up a three way meeting for later this week. 74733 13 srifenbark 2017-07-04 14:46:42 +0000 Hi, Creation of a "How-to" dev-manual has made moving the devtool flow that was in the dev-manual out. It essentially was deleted since what was in the sdk-manual was virtually identical. I did a bit of a "Tip" at the front end of the section to indicate that the devtool is not limited to just SDK development. http://www.yoctoproject.org/docs/2.4/sdk-manual/sdk-manual.html#using-devtool-in-your-sdk-workflow. If differences exist between SDK and non-SDK use, we can isolate them without having to duplicate this material, which is poor practice. I am taking ownership of this bug as it is all about the documentation. Setting it to IN PROGRESS REVIEW. Scott 74796 14 bluelightning 2017-07-06 07:05:27 +0000 I really don't like this. If you point people to the SDK manual you get everything in the context of usage within the SDK, which isn't very similar but not quite the same as usage next to the build system. The remainder of the SDK manual has nothing to do with that context. Is this just about saving us maintenance work at the expense of potential confusing the user? I had hoped that we'd be able to use includes to get around this. 74825 15 srifenbark 2017-07-06 15:26:00 +0000 Paul, I invite you to look at the 2.3 versions of these two areas. Here are the links: * dev-manual - http://www.yoctoproject.org/docs/2.3/dev-manual/dev-manual.html#using-devtool-in-your-workflow * sdk-manual - http://www.yoctoproject.org/docs/2.3/sdk-manual/sdk-manual.html#using-devtool-in-your-sdk-workflow I read through these and there is no difference except the placement. Can you point out where they differ? I am not against having these in separate places but given the fact that I could not find any differences and that the dev-manual is void of these sections now (no more chapter 4), I moved it. Let me know. Scott 74961 16 kristi 2017-07-12 16:05:01 +0000 Setting new milestone - Need Paul to review Kristi 78700 17 sjolley.yp.pm 2017-12-14 15:56:48 +0000 Paul Please review 79967 18 kristi 2018-03-23 12:02:52 +0000 Too much time has passed in review status without input - marking this one as RESOLVED.