B@D v1.0 release: documentation

Issue Background

• Once Gold Master is declared, the work on the documentation starts. Some of the tasks can start even before. This task in general takes place in parallel with the deployment task.
• This task in blocked by #142
• Feature page
  • In the previous release we did the minimum on the license compliance side. We will improve the situation on this release according to #140
  • This is the second formal release so we will need to start moving pages and keeping stable links for the newest version. Check how to do it with the current wiki.
• Technical instructions
  • This is in theory the content that should not change in structure.
  • Only updates to the new version should be needed, in principle.
• Download page
  • We need to consider this is the first time we will have two releases that can be downloaded.
  • Further actions towards meeting all the requirements from the compliance perspective will be taken.
• Landing page
  • No major changes required.
• FAQ page
  • Minor changes required like an additional question related with lab in a box
• Management page
  • This page was not created the previous release.
  • It has been moved since created so the links to it needs to be updated.
  • Content needs to be updated.
  • The marketing content will be moved to a new wiki page.
  • Improvements on the content of the delivery process section are required.
• Marketing page
  • Needs to be created a new marketing page where the current marketing content from the Management wiki page will be move to.
  • The new marketing contents will be published there, in this new page.

Issue description

Feature page

You can check the previous release feature page related task: #38 (closed)

• Move the current feature page
  • Add link to this new URL in:
    • The landing page
    • The download page
    • The new feature page
    • The former release announcement.
• Create a new wiki page in the same link that the feature page of the previous release was located.
• Copy the content from the old feature page to the new feature page, to use it as starting point.
• Update the software shipped table
  • Keep the current versions
• Extend the current description of what we are shipping with new information. Update the current information.
• Update and increase the number of links in the Interesting Links section. Include further links to technical information about the technologies used in this version of B@D.
• Update the Known issues section.
  • Go over the previous known issues:
    • Update the version number or the workaround for the current version.
    • Erase those that are not relevant for the current version.
• Update links to LAVA and kernelci description in the first section, when describing what is included in the box.
• Update the block diagram
  • Correct the components to adapt them to the current version.
  • Update the versions of the different components.
• Licenses.
  • Include a column on the components table with the licenses of the main components
  • Add a link to the original licenses description in each entry of the table.
  • Add a reference tot he license of the code developed by Codethink.
  • Add a reference to the CIP license policy.
• Include the link to the B@D 1.0 release announcement
• Communicate to the Product Owner that the feature page has been updated.

Technical instructions

You can check the previous release technical instructions related task: #39 (closed)

• The wiki pages that describes the technical documentation are the following:
  • Deploy B@D: there are 2 deployment options, Vagrant and the box.
  • Set up B@D: this page is independent of the deployment method
  • Board configuration page: how to connect BBB to the box.
  • Reference test cases: learn how to test
  • Known issues and trobleshooting: known issues and workarounds wiki page.
• Update the documentation for the v0.9 stable release
• Include references to the version of the release the documentation is for, in this case, v1.0
• Modify the links to the new repo location in each technical documentation wiki page.
• Update those areas affected by the LAVA update.

Download page

You can check the previous release technical instructions related task: #40 (closed)

• Create a new section called Latest Version. Name the former content as Previous versions.
  • The new section will go on top.
• Copy the content corresponding to the previous version in the new version section.
  • Erase from the previous version section everything but the table: instructions and links).
• Substitute the former entries on the table by the new ones. No changes in the structure required.
• Review in the download page the links to the technical documentation based on the critical path designed for users to walk through.
• Review in the download page the links to the further documentation pages, specially those that might have changed the URL, like the feature page.
• Include the new entries required by the licence compliance process #140
• Include the links of the downloadable archives.

Landing page

Check the previous release task related with this topic: #95 (closed)

• Change the link to the new feature page.
• Update the link to the management page.
• Create a link to the to new Marketing page

FAQ page

• Change reference to v0.9 by latest version with a link to the download page.
• Include in the BBB question a reference to:
  • Renesas board
  • Cyclone V
  • The TSC select the CIP supported boards.
• Include a question/answer that relates B@D with Lab in a box from AGL.

Management page

• Update the milestones diagram.
• Upload the updated milestone diagram.
• Up[date the key tasks diagram.
• Upload the updated key tasks diagram.
• Make the journal link more prominent
• Create a description and a link to the new Marketing page
• Release process howto: substitute the current reference to the previous release by the numbering convention ticket. Add also a description there.
• Link the main tasks of this release in the release process section, with a short description of the main phases of the release process.

Marketing page

• Create a new page for marketing content
• Move the current marketing content to this recently created Marketing page page.
• Link this mew marketing page on the
  • Management page (end)
  • Landing page
• Create an intro text in this new marketing page.

Acceptance criteria

• Feature page revision
  • Check links on the feature page
  • Check the versions and diagrams.
  • Check the whole content before release date.
• Technical instructions review
  • Deploy page reviewed.
  • Set up page reviewed.
  • Board configuration page reviewed.
  • Reference tests wiki page reviewed.
  • Known issues and workarounds wiki page reviewed.
• Download page
  • Review the license compliance requirements are met based on #140 .
  • Review the links on both tables
  • Review the links
• Landing page
  • Landing page links reviewed.
  • Landing page content reviewed.
• FAQ page
  • Check there is no reference to any specific version
  • Check the answer related with the boards has include other supported boards by CIP.
  • The entry related with Lab in a box has been added.
• Management page
  • New milestone diagram link:
  • New key tasks diagram link:
  • Marketing content moved.
  • Links to main tasks on delivery process section checked.
• Marketing page
  • New marketing wiki page link
  • Check link to this page on the landing page