Re: [Starlingx-discuss] StarlingX Documentation Initial Template
Hi Abraham, Will the documentation at https://docs.openstack.org/starlingx be both Developer Documentation and User Documentation ? ( I’m assuming that it will NOT be API documentation, I see discussions on that elsewhere. And would be located at https://developer.openstack.org/api-ref/starlingx/ ??? ) I am the main reviewer for all existing User Documentation for Titanium Cloud, so I’ll volunteer on being a core reviewer for this StarlingX Documentation ... please add me to the appropriate email lists. Thanks, Greg. From: "Arce Moreno, Abraham" <abraham.arce.moreno@intel.com> Date: Wednesday, August 1, 2018 at 11:54 AM To: "starlingx-discuss@lists.starlingx.io" <starlingx-discuss@lists.starlingx.io> Subject: [Starlingx-discuss] StarlingX Documentation Initial Template Dean, Here you have the high level overview of tasks to get started with our " StarlingX Documentation". @Hayde has raised her hand to help in this short term not time consuming assignment. Objective: Create a first "Gold Initial Commit" based in "Stx-Docs" project including high level requirements from OpenStack Documentation Guidelines so it can ported into the rest of our StarlingX projects. Phase 1: 1. Learning Resources 1.1 Read "OpenStack Documentation Contributor Guide" https://docs.openstack.org/doc-contrib-guide/index.html 2. Initial Code 2.1 Understand existing "Stx-Docs" repository and "docs/" implementation https://review.openstack.org/#/q/project:openstack/stx-docs 3. Translate important topics from "OpenStack Documentation Contributor Guide" into "Stx-Docs" commits: 3.1 Project guide setup 3.2 Writing documentation 3.3 Writing style 3.4 Building documentation 3.5 Landing pages on docs.openstack.org 4. Get Final Gerrit Reviews on commits and make changes 5. Have our "Gold Initial Commit" ready Phase 2: Once the first interaction is done we can take another repository to test our "Gold Initial Commit" having only modifications at the content level. Phase 3: With 2 interactions we are ready to easily move what we have learned and implemented in 2 projects to the rest of our StarlingX projects. Happy to hear your thoughts. _______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io<mailto:Starlingx-discuss@lists.starlingx.io> http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
On Wed, Aug 8, 2018 at 6:13 AM, Waines, Greg <Greg.Waines@windriver.com> wrote:
( I’m assuming that it will NOT be API documentation, I see discussions on that elsewhere. And would be located at https://developer.openstack.org/api-ref/starlingx/ ??? )
The actual location has not been finalized yet. I imagine it to be something like docs.starlingx.io.
so I’ll volunteer on being a core reviewer for this StarlingX Documentation ... please add me to the appropriate email lists.
You're on it! We are trying really hard to stay on a single list and use subject tags for filtering. dt -- Dean Troyer dtroyer@gmail.com
Thanks Greg, Dean!
( I’m assuming that it will NOT be API documentation, I see discussions on that elsewhere. And would be located at https://developer.openstack.org/api-ref/starlingx/ ??? )
The actual location has not been finalized yet. I imagine it to be something like docs.starlingx.io.
Taking stx-metal as our initial repository, please find both patches to review: [0] [Doc] OpenStack Documentation Contributor Guide [1] [Doc] OpenStack API Reference Guide Under Documentation and Infrastructure Sub-project [2] I am pointing to 2 wiki pages to document our analysis, learnings, tasks and updates: [3] StarlingX/Documentation [4] StarlingX/Developer_Guide/API_Documentation I will work on enabling API Guide and Release Notes for stx-metal to to enable the "gold commit pack" to easily take to the rest of the projects where needed.
so I’ll volunteer on being a core reviewer for this StarlingX Documentation ... please add me to the appropriate email lists.
You're on it! We are trying really hard to stay on a single list and use subject tags for filtering.
Welcome Greg! [0] https://review.openstack.org/#/c/590094 [1] https://review.openstack.org/#/c/590097 [2] https://wiki.openstack.org/wiki/StarlingX/Docs_and_Infra [3] https://wiki.openstack.org/wiki/StarlingX/Documentation [4] https://wiki.openstack.org/wiki/StarlingX/Developer_Guide/API_Documentation
On Wed, Aug 8, 2018 at 6:13 AM, Waines, Greg <Greg.Waines@windriver.com> wrote:
( I’m assuming that it will NOT be API documentation, I see discussions on that elsewhere. And would be located at https://developer.openstack.org/api-ref/starlingx/ ??? )
The actual location has not been finalized yet. I imagine it to be something like docs.starlingx.io.
How to decide where to land the documentation? 2 options: - docs.openstack.com - docs.starlingx.io [ OpenStack Documentation ] For each project we create source code directories to enable specific functionality: <stx-project>/docs/ General Documentation <stx-project>/api-ref/ API Reference <stx-project>/api-guide/ API Guide <stx-project>/releasenotes/ Release Notes Help Needed! Can you please help me to fill out ethercalc [0] which has the list of projects and the functionality that could be implemented with a Yes or No? This is in preparation to enable our Tech Writing team for the next release. [ docs.starlingx.io ] This option will allows us to take advantage of the infrastructure not only to create but also to land our documentation as follows, depending on what is the functionality available from the project: <stx-project>/docs/ -> docs.openstack.org/<stx-project> <stx-project>/api-ref/ -> developer.openstack.org/api-ref/<stx-project> <stx-project>/api-guide/ -> developer.openstack.org/api-guide/<stx-project> <stx-project>/releasenotes/ -> docs.openstack.org/releasenotes/<stx-project> [ docs.starlingx.io ] Source code directory structure can be kept however, what could be the landing process since it will be out of OpenStack infrastructure? How about the layout? Option 1 <stx-project>/docs/ -> docs.starlingx.io/<stx-project> <stx-project>/api-ref/ -> docs.starlingx.io/api-ref/<stx-project> <stx-project>/api-guide/ -> docs.starlingx.io/api-guide/<stx-project> <stx-project>/releasenotes/ -> docs.starlingx.io/releasenotes/<stx-project> Option 2 <stx-project>/docs/ -> docs.starlingx.io/<stx-project> <stx-project>/api-ref/ -> api-ref.starlingx.io/ <stx-project> <stx-project>/api-guide/ -> api-guide.starlingx.io/<stx-project> <stx-project>/releasenotes/ -> releaseanotes.starlingx.io/<stx-project> Option 3 Any other :) [0] https://ethercalc.openstack.org/sifnpbvze9lb
On Thu, Aug 9, 2018 at 4:33 PM, Arce Moreno, Abraham <abraham.arce.moreno@intel.com> wrote:
How to decide where to land the documentation? 2 options:
- docs.openstack.com
We will not be publishing things under openstack.org
- docs.starlingx.io
This or something else under starlingx.io
[ OpenStack Documentation ] For each project we create source code directories to enable specific functionality:
<stx-project>/docs/ General Documentation
/doc
<stx-project>/api-ref/ API Reference <stx-project>/api-guide/ API Guide <stx-project>/releasenotes/ Release Notes
yes
[ docs.starlingx.io ]
This option will allows us to take advantage of the infrastructure not only to create but also to land our documentation as follows, depending on what is the functionality available from the project:
<stx-project>/docs/ -> docs.openstack.org/<stx-project> <stx-project>/api-ref/ -> developer.openstack.org/api-ref/<stx-project> <stx-project>/api-guide/ -> developer.openstack.org/api-guide/<stx-project> <stx-project>/releasenotes/ -> docs.openstack.org/releasenotes/<stx-project>
FWIW OpenStack did some of the separation here due to the different teams responsible for the content. We may not have that need and want to stick to a simpler format with everything under a single site.
[ docs.starlingx.io ]
Source code directory structure can be kept however, what could be the landing process since it will be out of OpenStack infrastructure?
We need to get the server set up for this (via OpenStack Infra team) and set up the publishing jobs to populate it
How about the layout?
Option 1 <stx-project>/docs/ -> docs.starlingx.io/<stx-project> <stx-project>/api-ref/ -> docs.starlingx.io/api-ref/<stx-project> <stx-project>/api-guide/ -> docs.starlingx.io/api-guide/<stx-project> <stx-project>/releasenotes/ -> docs.starlingx.io/releasenotes/<stx-project>
I prefer this or something similar... dt -- Dean Troyer dtroyer@gmail.com
How to decide where to land the documentation? 2 options:
- docs.openstack.com
We will not be publishing things under openstack.org
Understood
- docs.starlingx.io
This or something else under starlingx.io
Understood
[ OpenStack Documentation ] For each project we create source code directories to enable specific functionality:
<stx-project>/docs/ General Documentation
/doc
Yep, typo
<stx-project>/api-ref/ API Reference <stx-project>/api-guide/ API Guide <stx-project>/releasenotes/ Release Notes
yes
:)
[ docs.starlingx.io ]
<stx-project>/docs/ -> docs.openstack.org/<stx-project> <stx-project>/api-ref/ -> developer.openstack.org/api-ref/<stx- project> <stx-project>/api-guide/ -> developer.openstack.org/api-guide/<stx- project> <stx-project>/releasenotes/ -> docs.openstack.org/releasenotes/<stx-project>
FWIW OpenStack did some of the separation here due to the different teams responsible for the content. We may not have that need and want to stick to a simpler format with everything under a single site.
Let me get into the next level of detail with respect to our source code structure and theme: [ Structure: Option 1 ] Aligned to OpenStack project conventions <stx-project>/docs/ <stx-project>/api-ref/ <stx-project>/api-guide/ <stx-project>/releasenotes/ [ Structure: Option 2 ] <stx-project>/docs/source/ <stx-project>/docs/api-ref/ <stx-project>/docs/api-guide/ <stx-project>/docs/releasenotes/ [ Theme ] Do we have a short and long term goal with respect to the theme? I assume we continue using sphinx and about its theme we have the following options: - default - continue with openstackdocstheme - a custom starlingx?
[ docs.starlingx.io ]
Source code directory structure can be kept however, what could be the landing process since it will be out of OpenStack infrastructure?
We need to get the server set up for this (via OpenStack Infra team) and set up the publishing jobs to populate it
Understood, any example in mailing lists or through a gerrit review which requests a non OpenStack landing site to learn from and start with this activity?
How about the layout?
Option 1 <stx-project>/docs/ -> docs.starlingx.io/<stx-project> <stx-project>/api-ref/ -> docs.starlingx.io/api-ref/<stx-project> <stx-project>/api-guide/ -> docs.starlingx.io/api-guide/<stx-project> <stx-project>/releasenotes/ -> docs.starlingx.io/releasenotes/<stx-project>
I prefer this or something similar...
Landing layout then to be defined after we work with OpenStack Infra team.
participants (3)
-
Arce Moreno, Abraham
-
Dean Troyer
-
Waines, Greg