diff --git a/specs/2019.03/approved/documentation-mega-spec.rst b/specs/2019.03/approved/documentation-mega-spec.rst new file mode 100644 index 0000000..caee8bf --- /dev/null +++ b/specs/2019.03/approved/documentation-mega-spec.rst @@ -0,0 +1,642 @@ + +Documentation re-org and user documentation framework +===================================================== + +This specification proposes changes to the structure of the StarlingX +documentation to make it easier for new contributors and users to find +the information they need. We are also proposing a number of new +documents to cover gaps in the current documentation set. This spec +defines the proposed new structure of the stx.docs repo and includes +links to the Storyboard entries for the new documents proposed. The +new documents needed have been prioritized by the Docs team to allow for +the implementation to occur over time. + +Story board entries for the numerous SB entries proposed here will +be created once the document is close to approval. + +Problem description +=================== + +The StarlingX documentation structure can be improved to provide more +information for new users and contributors, as well as providing additional +reference information for more experienced users. It can also be +improved to make it easier for users and contributors to navigate the +document hierarchy so they can find what they need. + +Use Cases +========= + +1. As a new user, I would like to learn the basics about StarlingX +so I can plan and complete an evaluation of the software. +2. As a user, I would like to learn how to deploy, install and run +StarlingX, so I can successfully deploy Starlingx for my Edge Cloud +applications. +3. As a user administering a StarlingX edge cloud deployment, I would like +to learn how to use all of the features of StarlingX and have all of +the API and CLI interfaces documented, so I can manage my +StarlingX Edge Cloud. +4. As a new contributor, I would like to learn about how to contribute +to the StarlingX project, so that my contributions are accepted. +5. As a new contributor, I would like to learn about the process +for accessing the StarlingX source code and building it from source, so +I can make changes and test them. +6. As a contributor, I would like to learn about the architecture of +StarlingX and the project’s development process, so I can contribute to +the project more effectively. + +Proposed Change +=============== + +This section describes the changes to be made to the documentation. The +changes are broken down into multiple stories each of which has a +priority as proposed by the Docs team. + +New landing page +---------------- + +We propose to change the StarlingX documentation hierarchy on +docs.starlingx.io from this: + +- Installation Guide +- Developer Guide +- Project Specifications +- REST API Reference +- Release Notes +- Contribute + +To this: + +- Introduction to StarlingX +- Deployment Guides +- Installation Guides +- Operation Guides +- Contributor Guides +- Releases and Release Notes +- Developer Resources + +Each of the new sections in the document hierarchy is described below. +Note that we are separating Deployment from Installation. We define +Deployment as all the steps needed starting from empty racks in the +data center to a running StarlingX instance. Installation is defined +as installing the software and is a subset of Deployment. Both sets +of documents will leverage content from the existing StarlingX documentation. + +SB entry: 2005000 +Priority: VH - release gating + +Introduction to StarlingX +------------------------- + +This new page in the document tree is a landing page is intended +to be a Quick Start for people who are new to StarlingX. It contains +links to the following documents: + +- StarlingX Project Introduction +- StarlingX for Kubernetes Users +- StarlingX for OpenStack Users +- StarlingX in a Box +- StarlingX Software Evaluation Guide +- Roadmap to StarlingX Documentation + +SB entry: 2005001 +Priority: VH - Release gating + +The following documents are included in this section of the documentation. + +**StarlingX Project Introduction (NEW)** +This document should start with a project overview with +respect to objectives, +capabilities, basic approaches. Introduce the concept of base +Kubernetes Cluster + optional OpenStack Cloud Application. Introduce +the various use cases for StarlingX and the available deployment +options. The document should include a link to the Release page, +noting that pre-built and tested images are available. +SB entry: 2005002 +Priority: VH - release gating + +**StarlingX for Kubernetes Users (NEW)** +This document should describe the Kubernetes solution installed +and supported by StarlingX; e.g. what Kubernetes services are +included, what networking options, what container runtime +options, what storage solutions and the local registry. It should +highlight the advantages of the way that StarlingX configures and +uses Kubernetes as opposed to standard Kubernetes. +SB entry: TBD +Priority: H + +**StarlingX for OpenStack Users (NEW)** +This document shall describe the OpenStack solution installed and +supported by StarlingX; e.g. what OpenStack Services are supported, +what Neutron backends are supported and what storage backends are +supported. This document shall highlight the advantages of the way +that StarlingX configures and uses OpenStack as opposed to standard +OpenStack. +SB entry: TBD +Priority: H + +**StarlingX in a Box (NEW)** +This doc will describe how to boot and run +“StarlingX in a Box” (SIAB). Once we actually create +it (SB 2004811). The document should take users through +the process of bringing OpenStack services +up and show them some basic commands +such as create VM, load image into VM, start/stop VM and other +similar commands. It should cover how to bring up StarlingX +Kubernetes, the basic K8S commands e.g. create a container, create +a service, launching a container application with a helm chart. +The challenge will be to not over document things documented elsewhere +or familiar to experienced OpenStack or K8S users, while +guiding less experienced users to performing real world tasks +in StarlingX. The team creating StarlingX in a Box may decide +to create an image with both the OpenStack and Kubernetes services +already up and running, in which case we don't need to document +the bring-up process here. +SB entry: 2005003 +Priority: VH - release gating + +**StarlingX Software Evaluation Guide (NEW)** +This is a new document that describes the key features of StarlingX +that we expect Edge Cloud users to be interested in, and how to +set up and operate a StarlingX system to showcase them. Without +over-documenting features already covered elsewhere - the goal of +this document is to be an appetizer and not the main course. +It should also describe +basic evaluation use cases and how to implement them in +StarlingX. The Document can start by directing evaluators to +the "StarlingX in a Box" document and then build off of that +to showcase more advanced features. It should call out the +open source functional and +performance test suites (once they exist) and how to run them. +The document’s main goal is to show users who are "kicking the tires" +of StarlingX how to use the key +differentiating features of StarlingX and guide them to a +very positive evaluation. +SB entry: TBD +Priority: M + +**Roadmap to the StarlingX Documentation (New)** +This new document provides the reader with a brief overview of +the entire documentation set. It could be based on use cases +listed above e.g. “if you are a dev looking to contribute, you +should read X, Y and Z. If you are an operator planning a +deployment read A & B.". The contents of this spec itself +may be a good starting place for this document. +SB entry: TBD +Priority: H + +Deployment Guides +------------------ + +This is a new landing page in the document hierarchy. The deployment +options can be defined on the landing page and/or in the Deployment Options +page - a brief version on the landign page with full details in the Options +page is suggested. The landing page contains +links to the following documents: + +- StarlingX Deployment Planning +- StarlingX Deployment Options +- All-in-one Simplex Deployment Guide +- All-in-one Duplex Deployment Guide +- All-in-one Duplex with up to 4 Computes Deployment Guide +- Standard with Controller Storage Deployment Guide +- Standard with Dedicated Storage Deployment Guide +- Standard with Ironic Deployment Guide +- Multi-Region Deployment Guide +- Distributed Cloud Deployment Guide + +SB entry: 2005004 +Priority: VH - release gating + +The following documents are included in this section of the documentation. + +**StarlingX Deployment Planning (New)** +This is a new document for how to plan a deployment of StarlingX. +Needs to include references to the Deployment Options (or maybe +just include it). Discuss why, how and when the various deployment +options should be used. More focused on how to define what +hardware to buy and how to cable it up. The existing HW +requirements documents would go here. +SB entry: 2005005 +Priority: VH - release gating + +**StarlingX Deployment Options (New)** +This is a new document that describes at a high level the different +deployment options for StarlingX. This could be part of the +Deployment Planning document at the author's discretion. +SB entry: 2005006 +Priority: VH - release gating + +All of the Deployment Guides below should include Deployment +Diagrams showing the logical topology and networking of each +deployment option, e.g. showing the various node types, the various +network types, the typical gateway routers, etc... This has been +explicitly requested on our mailing list. + +**All-in-one Simplex Deployment Guide (New)** +This is a new document that describes how to deploy StarlingX in +the All-in-one Simplex configuration. +SB entry: 2005007 +Priority: VH - release gating + +**All-in-one Duplex Deployment Guide (New)** +This is a new document that describes how to deploy StarlingX in +the All-in-one Duplex configuration. +SB entry: 2005008 +Priority: VH - release gating + +**All-in-one Duplex with up to 4 Computes Deployment Guide (New)** +This is a new document that describes how to deploy StarlingX in +the Duplex with Compute nodes configuration. Optionally, at the +discretion of the author of the All-in-one Duplex Deployment Guide, this +could be just an additional section of that document. +SB entry: 2005009 +Priority: VH - release gating + +**Standard with Controller Storage Deployment Guide (New)** +This is a new document that describes how to deploy StarlingX in +the Small Standard (no storage) configuration. +SB entry: 2005010 +Priority: VH - release gating + +**Standard with Dedicated Storage Deployment Guide (New)** +This is a new document that describes how to deploy StarlingX in +the Standard (with storage nodes) configuration. +SB entry: 2005011 +Priority: VH - release gating + +**Standard with Ironic Deployment Guide (New)** +This is a new document that describes how to deploy StarlingX in +the Standard configuration with OpenStack Ironic to allow use of +bare metal Compute nodes. This is basically just the existing +how-to doc on Ironic, updated to deploy it in a Container. At the +author's discretion, a separate Installation Guide for Ironic could +also be written. +SB entry: TBD +Priority: M + +**Multi-Region Deployment Guide (New)** +This is a new document that describes how to deploy StarlingX in +the Multi-Region configuration. +SB entry: 2005012 +Priority: VH - release gating + +**Distributed Cloud Deployment Guide (New)** +This is a new document that describes how to deploy StarlingX in +the Distributed Cloud configuration. +SB entry: 2005013 +Priority: VH - release gating + +Installation Guides +------------------- + +This is a new landing page in the document hierarchy. It contains +links to the following documents: + +- All-in-one Simplex Installation Guide +- All-in-one Duplex Installation Guide +- All-in-one Duplex with Computes Installation Guide +- Standard with Controller Storage Installation Guide +- Standard with Dedicated Storage Installation Guide +- Multi-Region Installation Guide +- Distributed Cloud Installation Guide +- Additional OpenStack Services Installation Guide + +SB entry: 2005174 +Priority: VH - release gating + +The following documents are included in this section of the documentation. + +**All-in-one Simplex Installation Guide (New)** +This is a new document that describes how to install StarlingX in +the All-in-one Simplex configuration. +SB entry: 2005175 +Priority: VH - release gating + +**All-in-one Duplex Installation Guide (New)** +This is a new document that describes how to install StarlingX in +the All-in-one Duplex configuration. +SB entry: 2005176 +Priority: VH - release gating + +**All-in-one Duplex with Computes Installation Guide (New)** +This is a new document that describes how to install StarlingX +in the Duplex with Compute nodes configuration. +SB entry: 2005177 +Priority: VH - release gating + +**Standard with Controller Storage Installation Guide (New)** +This is a new document that describes how to install StarlingX +in the Small Standard (no storage) configuration. +SB entry: 2005178 +Priority: VH - release gating + +**Standard with Dedicated Storage Installation Guide (New)** +This is a new document that describes how to install StarlingX +in the Standard (with storage nodes) configuration. +SB entry: 2005179 +Priority: VH - release gating + +**Multi-Region Installation Guide (New)** +This is a new document that describes how to install StarlingX +in the Multi-Region configuration. +SB entry: 2005180 +Priority: VH - release gating + +**Distributed Cloud Installation Guide (New)** +This is a new document that describes how to install StarlingX +in the Distributed Cloud configuration. +SB entry: 2005181 +Priority: VH - release gating + +**Additional OpenStack Services Installation Guide (New)** +This is a new document that describes how to install and configure +additional OpenStack services (beyond those supported by StarlingX) +in a StarlingX deployment. Example services include Octavia, +Trove and Sahara, all of which have been mentioned in the +community as of interest. +SB entry: TBD +Priority: L + +Operation Guides +---------------- + +This is a new landing page in the document hierarchy. It is intended to +serve as the home page for “how to” documents and user/operator focused +documentation. The page should contain links to the following documents: + +- StarlingX API Reference +- StarlingX CLI Reference +- StarlingX Data Network Configuration +- StarlingX CEPH Storage Configuration +- StarlingX SDN Networking +- StarlingX Kubernetes Cluster Guide +- StarlingX SWIFT Configuration and Management +- StarlingX Fault Management +- StarlingX Patching Guide +- StarlingX Upgrade Guide + +SB entry: 2005182 +Priority: VH - release gating + +**StarlingX API Reference** +This is the existing API Reference documentation. + +**StarlingX CLI Reference (New)** +This is a new document the defines all of the CLI commands +accepted by the StarlingX unique services (the Flock). +SB entry: TBD +Priority: M + +**StarlingX Data Network Configuration (New)** +This is a new document for how to configure the data networks. At +the author's discretion this can be covered in the deployment guides. +SB entry: TBD +Priority: M + +**StarlingX CEPH Storage Configuration (New)** +This is a new document for how to configure CEPH. At the author's +discretion this could also be a part of the deployment guides. +SB entry: TBD +Priority: M + +**StarlingX SDN Networking (New)** +This is a new document for how to configure SDN networking. +SB entry: TBD +Priority: L + +**StarlingX Kubernetes Cluster Guide (New)** +This is a new document for how to operate the Kubernetes +within StarlingX. It should cover a description of how we use +the Armada component, how helm charts are managed within StarlingX, +how overrides for helm charts are configured/saved/edited. +SB entry: TBD +Priority: M + +**StarlingX SWIFT Configuration and Management (New)** +This is a new document describing how to configure and use +SWIFT within StarlingX. +SB Entry: TBD +Priority: M + +**StarlingX Fault Management (New)** +This is a new document describing the fault management +capabilities of StarlingX and how to use them, how to find and +read logs, etc… It should call out and provide a link to the SNMP MIB. +SB entry: TBD +Priority: M (H?) + + +**StarlingX Patching Guide (New)** +This is a new document describing the software patching +capabilities of StarlingX and how to use them. +SB entry: TBD +Priority: L + +**StarlingX Upgrade Guide (New)** +This is a new document describing the software upgrade +capabilities of StarlingX and how to use them. +SB entry: TBD +Priority: L + +Contributor Guides +------------------ + +This is a new landing page in the document hierarchy. It is intended +to serve as the home page for “how to” documents and user/operator +focused documentation. The page should contain links to the +following documents: +- StarlingX Contributor Guide +- StarlingX Development Process +- StarlingX Build Guide +- StarlingX API Contributor Guide +- StarlingX Release Notes Contributor Guide +- StarlingX Documentation Contributor Guide + +SB entry: 2005183 +Priority: VH - release gating + +**StarlingX Contributor Guide (New)** +This is a new document providing a high level overview of how +to contribute to StarlingX. It should describe the +communication channels that are used by the project team, the +way we have divided up the project into sub-projects, our +wiki page, our weekly community and sub-project meetings, and +other similar topics. It should point to the build and +installation documents and describe our expectations for +pre-commit testing needed before changes can be accepted. It +should point to the project's formal Governance documents +and describe the roles of the TSC members and Core Reviewers +in reviewing and approving code changes. +SB entry: TBD +Priority: H + +**StarlingX Development Process (New)** +This is a new document that can leverage existing content from +the wiki. The document should cover the basic tools used +(git / gerrit / etc…), the feature development and spec +approval process, the bug resolution process, our release +planning process and other similar topics. + +Initially this document can be a link to the current +wiki pages that describe +the development process. Over time, we can consider moving the wiki +content into the git managed formal documentation. +SB entry: TBD +Priority: H +SB entry to fix the wiki content: 2005173 +Priority: H + +**StarlingX Build Guide** +This is the existing Build documentation, updated as needed to +fit within the new hierarchy and for the Containers changes. It should +include a description of the build artifacts hosted by the third party and +how to use the build to leverage them. +SB entry: 2005184 +Priority: VH - release gating + +**StarlingX API Contributor Guide** +This is the existing API Contributor Guide + +**StarlingX Release Notes Contributor Guide** +This is the existing Release Notes Contributor Guide + +**StarlingX Documentation Contributor Guide** +This is the existing Documentation Contributor Guide + +Releases and Release Notes +-------------------------- + +This should be a landing page with links to the publicly +available pre-built images and the Release +notes for all releases. Releases that are no longer supported should +be included (for historical reasons) but should be marked as “obsolete” +or “unsupported”. +SB entry: 2995185 +Priority: VH - release gating + +Developer Resources +------------------- + +This is a new landing page within the documentation and will contain +links to the following documents: + +- How to Navigate the StarlingX Source Code +- StarlingX Architecture Documents +- StarlingX Specifications + +SB entry: 2005186 +Priority: VH - release gating + +**How to Navigate the StarlingX Source Code (New)** +This is a new document describing the structure, layout and high +level architecture of the StarlingX git repos and source code. +SB entry: TBD +Priority: H + +**StarlingX Architecture Documents (New)** +This is a landing page for architecture documents, which do not +yet exist. +SB entry: TBD +Priority: L + +**StarlingX Specifications** +This is a link to the existing StarlingX Specifications page. + +Alternatives +============ + +There are many ways to organize the StarlingX document repository. The +proposal here is the result of multiple discussions, drafts and reviews +within the Docs team. + +Data model impact +================= + +None + +REST API impact +=============== + +None + +Security impact +=============== + +None +Other end user impact +===================== + +End users should find it significantly easier to deploy and manage StarlingX +Edge Clouds. New contributors should find it significantly easier to +make contributions to the project. + +Performance Impact +================== + +None + +Other deployer impact +===================== + +None + +Developer impact +================ + +None + +Upgrade impact +============== + +None + +Implementation +=============== + +This work will be implemented as a set of related Storyboard entries, as +called out in the Proposed Change. Each Story has a priority defined +for it so the work can be managed over time. + +Assignee(s) +=========== + +Members of the Docs team will provide guidance and support. Responsibility +for the Documentation will need to be distributed across the StarlingX +sub-projects, to allow the work to be done by those most familar with the +software and to ensure the effort is scalable and manageable. + +Primary assignee: +================= + +Several will be needed. + +Other contributors: +=================== + +Many will be needed. + +Repos Impacted +============== + +Stx.docs and likely the Flock services repos + +Work Items +========== + +See the SB entries called out in the Proposed Change + +Dependencies +============ + +None significant + +Testing +======= + +Testing will be needed to ensure that the documents written accurately +describe the software. + +Documentation Impact +==================== + +Lots :)