From 7bd94d09134923dd570db9f765695479d2745e93 Mon Sep 17 00:00:00 2001 From: Sean Roberts Date: Tue, 23 Jun 2015 15:28:58 -0700 Subject: [PATCH] add doc spec reorganizing the existing docs to be more openstack docs friendly and easier for new users. Partially Implements: blueprint liberty-doc-updates Change-Id: I6d514dfb805738a73dac235d886364e5d7187084 --- specs/kilo/doc-updates.rst | 192 +++++++++++++++++++++++++++++++++++++ 1 file changed, 192 insertions(+) create mode 100644 specs/kilo/doc-updates.rst diff --git a/specs/kilo/doc-updates.rst b/specs/kilo/doc-updates.rst new file mode 100644 index 0000000..aaa46fa --- /dev/null +++ b/specs/kilo/doc-updates.rst @@ -0,0 +1,192 @@ +.. + This work is licensed under a Creative Commons Attribution 3.0 Unported + License. + + http://creativecommons.org/licenses/by/3.0/legalcode + + +Title of your blueprint +======================= + +Liberty release documentation updates + + +Problem Description +=================== + +The documentation needs to be easy for new users and contributors while +following similar OpenStack docs structure and conventions. + + +Proposed Change +=============== + +Organize the documentation around four sections: What Is Akanda, Installing +Akanda, Operating Akanda, and Akanda Developer Guide. + +This change will make the Akanda documentation [1] read similar to the existing +OpenStack documentation [2]. This will also prepare the Akanda documentation +for merging with the OpenStack documentation. + +What Is Akanda section will hold the existing High Level Architecture, +Service VM Orchestration and Management, The Service VM sections. These pages +VM will be renamed to Instance. We will +add user documentation for demonstrating akanda, understanding how it +orchestrates network services, and how to compare (or not to) akanda to other +SDN options. Add some details around EW and NS frame/packet flow between +compute nodes. Make IPv6 support very clear and called out. Explain the driver +concept and how it will make support of new Neutron Advanced services easier. +Additionally provide understanding of how Akanda integrates with Neutron. Say +all this without duplicating any of the existing OpenStack documentation. + +Installing Akanda section will hold the existing Akanda Developer Quickstart. +Adding installing from tarballs, source, and eventually distribution. Known good +configurations will also be part of this section. + +Operating Akanda will hold the existing Operation and Deployment and +Configuration Options. We will add the training material here. We will need to +add details on dynamic routing support, how the configuration drift support +works and is managed. Links to supporting ML2 drivers like linuxbridge and OVS. +Making it clear how Akanda supports common Neutron configurations and +configuration changes. Add details on supporting VXLAN overlay and Lightweight +Network Virtualization (LNV) (Hierarchical Port Binding) with Akanda. + +Akanda Developer Guide will hold the details on setting up the developer +environment, testing code locally, explaining the CI tests, along with some +references to Neutron dependencies. This entire section will move to the +Akanda developer reference section here [3], once the Akanda project is +accepted into the OpenStack org repo. + +This spec also includes the use of docstrings in the code. We will start with +updating the rug code with docstrings as the most critical. + + +Data Model Impact +----------------- + +n/a + + +REST API Impact +--------------- + +n/a + + +Security Impact +--------------- + +n/a + + +Notifications Impact +-------------------- + +n/a + + +Other End User Impact +--------------------- + +n/a + + +Performance Impact +------------------ + +n/a + + +Other Deployer Impact +--------------------- + +n/a + + +Developer Impact +---------------- + +Updating the documentation structure will make it easier for new contributors +to join the Akanda project. As Akanda joins the OpenStack org repo structure, +it will make setting up the devref material very easy. + + +Community Impact +---------------- + +The OpenStack community will better understand what the Akanda project is +about and why it is important with clear documentation. + + +Alternatives +------------ + +* Leave documentation as is +* Wait until the Akanda project is moved into the OpenStack org repo before +updating the documentation structure. + + +Implementation +============== + +Assignee(s) +----------- + +Sean Roberts (sarob) + + +Work Items +---------- + +* Create a patch to restructure the Akanda documentation +* Add new content from slides and other sources +* After Akanda gets moved into OpenStack org repos, move the Akanda developer +reference to doc.openstack.org/developer/akanda/devref/ + + +Dependencies +============ + + +Testing +======= + +Tempest Tests +------------- + +n/a + + +Functional Tests +---------------- + +n/a + + +API Tests +--------- + +n/a + + +Documentation Impact +==================== + +User Documentation +------------------ + +See the proposed change section + + +Developer Documentation +----------------------- + +See the proposed change section + + +References +========== + +[1] http://docs.akanda.io/ +[2] http://docs.openstack.org/ +[3] http://docs.openstack.org/developer/openstack-projects.html