Development Manual Rework

This page will propose an outline for Development Manual refactoring work. See also bug #11630

The way Henry described this yesterday, customers use the "getting started" guide to learn how to bring up a vanilla image, but then don't know how to approach their own custom situation. This should be a TRANSITION DOCUMENT - how to use YP once you have gotten your feet wet in a controlled situation. Feel free to delete this, I don't know how you folks work in the WIKI and I'm assuming this may not be it.

I would suggest organizing this in a couple of ways - and this might be better in a google doc, frankly. 1) by what people need to do to get started

  a) where to start to support a platform
     1. find a BSP and test it
  b) how to add support for platform components
  c) how to slim down an image size
     1. Remove code automatically included
     2. design your own BSP fine tuned to exclude extra code, unneeded support code
  d) How to approach setting up a development environment
  e) How use layers to create a flexible long term design, and recipes
  d) How do you start a new project vs build off an existing one   
  e) How do you set up a team sharable development environment (sstate)
  f) Here are some of the most common commands 
  g) How to deal with CVEs and code branches

2) By helping them collect the information they need in order to make set up decisions Brent had a great idea to make this a SW Wizard that would step a new user through a series of questions and give them at least one solution on how to proceed.

  a) what platform are you using
  b) will you include an application as part of the image or will it run on the image
  c) what is the configuration of the team (system developers, app developers, etc)
  c) How to help them choose the right kernel
  d) etc.

Notes for Chapter 4 of the dev-manual:

Section 4.1 - "System Development Workflow"

Introductory material that will follow the subsections. Standard stuff to be adjusted depending on where it lands in the YP doc set.

Section 4.1.1 - "Developing a Board Support Package (BSP)"

Although the steps in this section are technically procedural, the level is more conceptual. We should move this discussion to the ref-manual and group it under some sort of new "concepts" heading where conceptual information is discussed. That is one idea. Another, is to create a conceptual section in the BSP Guide to hold this information. One thing we have not discussed is the fate of the BSP Guide in regards to the restructuring of the dev-manual to a task-based document. In any case, the current "Developing a Board Support Package (BSP)" section in the dev-manual is out. If we want to replace it in the dev-manual with something more concrete, then I suggest a real example that would be in the form of what is on this dated wiki page - https://wiki.yoctoproject.org/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another.

Section 4.1.2 - "Modifying the Kernel"

The information in this section is very conceptual and does not belong in the dev-manual. Solution for this section is similar to what I suggested for the "Developing a Board Support Package (BSP)" section above. However, this is kernel related so perhaps moving this kernel information to the kernel-dev manual. Again, if we want to have some concrete example in the dev-manual that is based on the conceptual information here, then we create a real example and use that and tie it to specific tasks.

Section 4.2 - "Application Development Workflow using and SDK"

This section can go away I think. We have the SDK manual and all it is here in the sdk-manual is a pointer to that manual.

Section 4.3 - "Modifying Source Code"

This section is conceptual by nature. Again, high-level procedures to support the concepts but I don't think they should be in the dev-manual. Both devtool and Quilt are covered in this section, and both regarding workflows designed to help the user modify source code. The actual need for this introductory stuff in 4.3 depends on really where the devtool and Quilt sections ultimately reside.

Section 4.3.1 - "Using devtool in Your Workflow"

These concepts belong in the ref-manual. Right now, this material is virtually duplicated in the sdk-manual. It should be one area and then any SDK-specific stuff can be captured in the sdk-manual. The section to put this in in the ref-manual would be under a "Concepts" heading and then maybe under something like "Workflows".

Section 4.3.2 - "Using Quilt in Your Workflow"

These concepts belong in the ref-manual in a new "Workflows" section bundled under some concepts heading. I can see creating an actual example that works and using it as a section in the dev-manual. The conceptual version from the ref-manual can reference into that example.

Section 4.3.3 - "Finding Temporary Source Code"

The reason this section is where it is was to support the Quilt workflow. If "Finding your Source Code" is a separate enough task to be in the dev-manual, then we can create a set of steps to walk a user through that give creation of some piece of software and maybe a kernel build. They seem to be different based on what you are building unless I am mis-understanding it.

Section 4.4 - "Image Development Using Toaster"

The reason this section exists is it was a development workflow and bundled in this overarching section. It is pretty much a placeholder and could be removed. There are ample areas where we can mention Toaster as a way of developing an image and then linking to the Toaster manual. If we have a workflow concepts section in the ref-manual, it can be mentioned there as a type of workflow.