See comments below,
Greg.

 

From: "Arce Moreno, Abraham" <abraham.arce.moreno@intel.com>
Date: Monday, September 17, 2018 at 10:37 PM
To: "starlingx-discuss@lists.starlingx.io" <starlingx-discuss@lists.starlingx.io>
Subject: [Starlingx-discuss] Developer Guide, Next Steps

 

Based on recent recommendations to improve our sync up between our tools and documentation,

we required your feedback on the required changes to our documentation regarding the build

of our ISO.

 

The high level structure of actual guides found under StarlingX main wiki [0] page how our community

can interact is:

 

- [1] Developer Guide

- [2] Installation Guide Virtual Environment

- [3] Testing Guide

[Greg]

Because a normal user has to build the ISO in order to use StarlingX,
I would have the following top-level guides

 

·         Build Guide

·         Installation Guide

·         User Guide

·         Contributor Guide

 

 

 

[ Profile of Users ]

 

In preparation to our release and considering the upcoming work based on stxb tool [4] [5] which will simplify

the build of an ISO, we are targeting two types of users which will impact the existing "Developer Guide" [1]:

 

- Users "Profile A" building StarlingX using stbx tool with the only objective to have the ISO, no need to

  debug / modify / whatever our code.

- Users "Profile B" with the need to get inside the container to debug / modify / whatever our code.

 

Due to community culture / non-native English speakers we are,  how would you called those 2 different

"wiki pages" / "sections" where both Users "Profile A" and "Profile B" will find their instructions:

 

- Users "Profile A": User Guide? Getting Started Guide?

- Users "Profile B": Contributor Guide? Developer Guide?

[Greg]

I would use:

·         User Guide

·         Contributor Guide

 

 

 

[ Sources of Documentation ]

 

Regarding the source of documentation we have 3 places:

 

- [1] The Developer Guide Wiki page, already populated, to be changed based in your feedback asked above. 

- [6] The README file under stx-tools repository, already populated.

- [7] The doc/ directory under stx-tools repository, not populated and not for this release, mid-term scope.

 

In preparation to our release and as a short term solution to keep updated one single place

we are targeting to make our wiki [0] our official source, removing all content from the README [6] keeping

only a link to the wiki page.

 

If there is a another proposal please let us know.

 

[0] https://wiki.openstack.org/wiki/StarlingX

[1] https://wiki.openstack.org/wiki/StarlingX/Developer_Guide

[2] https://wiki.openstack.org/wiki/StarlingX/Installation_Guide

[3] https://wiki.openstack.org/wiki/StarlingX/Testing_Guide

[4] http://lists.starlingx.io/pipermail/starlingx-discuss/2018-September/001001.html

[5] https://review.openstack.org/#/c/601366/

[6] https://git.openstack.org/cgit/openstack/stx-tools/tree/README.rst

[7] https://git.openstack.org/cgit/openstack/stx-tools/tree/doc/source/index.rst

 

 

_______________________________________________

Starlingx-discuss mailing list

Starlingx-discuss@lists.starlingx.io

http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss