[Starlingx-discuss] DRAFT: initial version of a spec for restructuring docs.starlingx.io

[Jones, Bruce E]

This is a snapshot of a work in progress specification for an effort to rearrange and restructure our formal documentation, and to add new documents.  The intent is to make it easier for people new to the project to find out what they need to know to get started, and to provide an organization for our other documents that makes reference material easier to find.

Comments and feedback welcome either in email or in the google doc we're currently using [0].

Thank you!

         Brucej

[0] https://docs.google.com/document/d/1DBV-EN5BGoYtsReSleDa6Emerg7oxjL_HYmR9kpJ68Q/edit?usp=sharing



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 will define the proposed new structure of the stx.docs repo and include links to the SB entries for the new documents proposed.

Problem description
===================
The StarlingX documentation structure should be improved to provide more information for new users and contributors, as well as providing additional reference information for more experienced users.  It should 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 brand new user, I would like to learn the basics about StarlingX so I can plan my initial deployment
  2.  As a user, I would like to learn how to install, deploy and run StarlingX, so I can learn about it, try it out and evaluate it.
  3.  As a user, I want to be able to plan my deployment of StarlingX so I can ensure my deployment is successful
  4.  As a user deploying StarlingX in production, 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.
  5.  As a brand new contributor, I would like to learn about the process for building StarlingX from source code
  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.

Proposed Change
===============
We propose to change the StarlingX documentation hierarchy from this:
     Installation Guide
     Developer Guide
     Project Specifications
     REST API Reference
     Release Notes
     Contribute
To this:
Introductory Guides - Read This First!
How to deploy and use StarlingX
StarlingX In A Bottle
Releases and Release Notes
Installation and Deployment Guides
Evaluation Guide
Operation Guides
How to contribute to StarlingX
Contributor Guides
StarlingX Internals
Architecture Documents
Specifications
Reference Documents
SB link for the restructuring: TBD

New Documents
-------------
This section describes the new documents to be created.

Introductory Guides - Read This First!
++++++++++++++++++++++++++++++++++++++
This document shall contain:
A high level overview of StarlingX discussing the key use cases and capabilities of the system
A link to "Introduction to StarlingX"
A link to "StarlingX for OpenStack users"
A link to "StarlingX for Kubernetes users"
A link to "StarlingX Background Information"
SB entry: TBD

Introduction to StarlingX
+++++++++++++++++++++++++
This document should start with a project overview wrt objectives, capabilities, basic approaches.  Introduce the concept of base Kubernetes Cluster + optional OpenStack Cloud Application.  Then provide a high level description of how to download, install, deploy and run StarlingX.  It should highlight the deployment options and how they can be used to implement the use cases in the Read This First document.
SB entry: TBD

StarlingX for OpenStack Users
+++++++++++++++++++++++++++++
This document shall highlight key similarities and differences between StarlingX and standard OpenStack.
SB entry: TBD


StarlingX for Kubernetes users
++++++++++++++++++++++++++++++
This document shall highlight key similarities and diffs between STX and standard Kubernetes.
SB entry: TBD

StarlingX Background Information
++++++++++++++++++++++++++++++++
This document shall contain a sanitized version of Abraham's internal New Hire spreadsheet.
SB entry: TBD

How to deploy and use StarlingX
+++++++++++++++++++++++++++++++
This page will describe at a high level how to install, deploy and use StarlingX.  It will include links to:
StarlingX In A Bottle
Releases and Release Notes
Installation and Deployment Guides
Operation Guides
SB entry: TBD

StarlingX in a Bottle
+++++++++++++++++++++
This page will describe how to boot and run the "StarlingX in a Bottle" (SIAB).  Once we actually create it (insert SB link here).
The document should take users through the process of bringing SIAB up and show them some basic commands (create VM, load image into VM, start/stop VM, etc...)
SB entry: TBD

Releases and Release Notes
++++++++++++++++++++++++++
This should be a landing page with links to the Cengn images and 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: TBD

Installation and Deployment Guides
++++++++++++++++++++++++++++++++++
THIS SECTION NEEDS WORK.
This is likely our current documents, with new and changed content to describe the major components of the system, the various deployment options, guidance for which ones to deploy for various use cases, and all the other details in the StarlingX Deployment Options presentation shared by Greg.
We should consider separate documents for installation and deployment.  We should also consider having separate deployment documents for each option.  We should also consider separate documents for deploying optional components (e.g. all of OpenStack and Ironic in an OpenStack deployment).  We should also consider a Planning document that will help users figure out how to build the physical resources (equipment) needed to run StarlingX (e.g. hardware requirements, etc...)
SB entry: TBD

StarlingX Evaluation Guide
++++++++++++++++++++++++++
This is a new document describing how we expect end users who are new to StarlingX to evaluate the software.  It should describe basic evaluation use cases and how to implement them in StarlingX.  It should call out the open source functional and performance test suites (once they exist) and how to run them.

StarlingX Operation Guides
++++++++++++++++++++++++++
THIS SECTION NEEDS WORK
This document will be a landing page linking to a collection of other documents describing in detail how to operate a StarlingX Edge Cloud.  TODO: Define those documents.



Contributor Guides
++++++++++++++++++
This is our current Contributor Guides.  Additional content is likely needed.  TODO: Review the current guide(s) and define changes/additions needed.

StarlingX Internals
+++++++++++++++++++
This page is a landing page, linking to the Architecture documents (which don't exist...), the current link to the StarlingX specifications and a new landing page for the Reference docs
SB entry: TBD

Architecture Documents
++++++++++++++++++++++
This is a placeholder (for now) for any Arch Docs that may be produced.
SB entry: TBD

Reference Documents
+++++++++++++++++++
This is a landing page linking to the API documentation and to the new CLI documentation pages.
SB entry: TBD

CLI Reference Documents
+++++++++++++++++++++++
This is a set of pages/documents that fully define the Command Line Interface for each StarlingX component.
SB entry: TBD



Alternatives
============

There are likely many ways to organize the StarlingX document repository.  This way seems reasonable and extensible to me :).

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.

Performance Impact
==================

None

Other deployer impact
=====================

None

Developer impact
================

Developers will have to maintain additional documents.  Since these documents will help them do their jobs, it's worth the effort :)

Upgrade impact
==============

None

Implementation
===============

This work will be implemented as a set of related Storyboard entries, as called out in the Proposed Change.

Assignee(s)
===========

Members of the Docs team will lead.  Contributions from the broader community will be needed.

Primary assignee:
=================
TBD
Other contributors:
===================
TBD
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 :)


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.starlingx.io/pipermail/starlingx-discuss/attachments/20190124/a2030d76/attachment-0001.html>