[Starlingx-discuss] Developer Guide, Next Steps

[Waines, Greg]

See comments below,
Greg.

From: "Arce Moreno, Abraham" <abraham.arce.moreno at intel.com>
Date: Monday, September 17, 2018 at 10:37 PM
To: "starlingx-discuss at lists.starlingx.io" <starlingx-discuss at 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 at lists.starlingx.io<mailto:Starlingx-discuss at lists.starlingx.io>
http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss

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