Bug 9566

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

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.

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

Hey, 

I am not doing anything drastic to these sections until we get some consensus on what we would like.

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

I'm going to assign this back to Scott since it's a documentation internal  structure issue now.

Setting to IN PROGRESS DESIGN as I need to figure this one out.

Scott

Pushing this to 2.3 M4.  I need other's input.  Setting to NEEDINFO

scott

Henry to ping Paul and get back to Scott.

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.

It appears Henry has answered the question.

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.

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

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.

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

Setting new milestone - Need Paul to review

Kristi

Paul Please review

Too much time has passed in review status without input - marking this one as RESOLVED.