I plan to be in the IRC meeting tomorrow but I don't want to fill the time trying to type all this in...
I am working on expanding the Getting Started Guide [1]. Work in progress is being merged into a getting-started branch [2] which despite the branch name, includes changes to the entire IoT docs site. I am focusing the Getting Started docs on getting an image booted (VM or Physical), with a user, and applying updates (even though there are not currently any updates to apply). Other topics will be in a separate guide (more below). I have added a placeholder for an "Obtaining Images" page which will provide context and point to the not yet available iot.fedoraproject.org page [3] I also have taken some of the the other small topics already on the site and created a "User Guide" section. I see a number of ideas on the SilverBlue pages [4] that could eventually be modified for IoT and added here as well.
With the first PR, Peter made a side comment and wondered about also a "Developer Guide". Silverblue just uses "Silverblue Guide" rather than calling it a User Guide and it does have some topics ("Generating Your Own SilverBlue ISO" for example) which could be considered developer rather than user. The Fedora Docs site has a "Contributor Guide" [5] including how to build a local preview.
So my first set of questions: *Is there a significant difference in what a "user" vs "developer" would need to know? (I hope that developers are also users!) If so, what would those developer specific topic be?
*Would a contributor guide be more in line with topics not thought of as user guide materials? It can have some of the more technical tasks needed for self QA before a PR as well as other process information.
*What would you like to see as the title for a guide that has the "next steps" beyond getting started? Leave my (admittedly administrator/user biased) instinct to call it a "User Guide" or make it more general as "IoT Guide"? (You may have different answers depending on the "all in one" vs "multi" guides outcome.)
I plan to be in the IRC meeting tomorrow.
Thanks! Susan
[1] https://docs.fedoraproject.org/en-US/iot/getting-started/ [2] https://pagure.io/fedora-iot/iot-docs/tree/getting-started [3] based off https://iot.stg.fedoraproject.org/ but with working Verify pages. [4] https://docs.fedoraproject.org/en-US/fedora-silverblue/ [5] https://docs.fedoraproject.org/en-US/fedora-docs/contributing/
On Wed, Feb 6, 2019 at 12:49 AM Susan Lauber laubersm@fedoraproject.org wrote:
I plan to be in the IRC meeting tomorrow but I don't want to fill the time trying to type all this in...
I am working on expanding the Getting Started Guide [1]. Work in progress is being merged into a getting-started branch [2] which despite the branch name, includes changes to the entire IoT docs site. I am focusing the Getting Started docs on getting an image booted (VM or Physical), with a user, and applying updates (even though there are not currently any updates to apply). Other topics will be in a separate guide (more below). I have added a placeholder for an "Obtaining Images" page which will provide context and point to the not yet available iot.fedoraproject.org page [3] I also have taken some of the the other small topics already on the site and created a "User Guide" section. I see a number of ideas on the SilverBlue pages [4] that could eventually be modified for IoT and added here as well.
With the first PR, Peter made a side comment and wondered about also a "Developer Guide". Silverblue just uses "Silverblue Guide" rather than calling it a User Guide and it does have some topics ("Generating Your Own SilverBlue ISO" for example) which could be considered developer rather than user. The Fedora Docs site has a "Contributor Guide" [5] including how to build a local preview.
So my first set of questions: *Is there a significant difference in what a "user" vs "developer" would need to know? (I hope that developers are also users!) If so, what would those developer specific topic be?
I would suggest the later is an evolution of the former. I would expect a user would just want to deploy the base and a selection of containers on top. A developer in contrast might want to package up an application stack in to a container(s), develop an app on top, enable/support new HW or addons etc
*Would a contributor guide be more in line with topics not thought of as user guide materials? It can have some of the more technical tasks needed for self QA before a PR as well as other process information.
Seems reasonable.
*What would you like to see as the title for a guide that has the "next steps" beyond getting started? Leave my (admittedly administrator/user biased) instinct to call it a "User Guide" or make it more general as "IoT Guide"? (You may have different answers depending on the "all in one" vs "multi" guides outcome.)
I think IoT guide is misleading, the term IoT can mean anything especially in this context, open to suggestions on the "next steps" guide.
I plan to be in the IRC meeting tomorrow.
Thanks! Susan
[1] https://docs.fedoraproject.org/en-US/iot/getting-started/ [2] https://pagure.io/fedora-iot/iot-docs/tree/getting-started [3] based off https://iot.stg.fedoraproject.org/ but with working Verify pages. [4] https://docs.fedoraproject.org/en-US/fedora-silverblue/ [5] https://docs.fedoraproject.org/en-US/fedora-docs/contributing/
-- Susan Lauber, (CCAH, RHCX, RHCA, RHCSS, RHCVA, CISSP) Lauber System Solutions, Inc. http://www.laubersolutions.com gpg: 15AC F794 A3D9 64D1 D9CE 4C26 EFC3 11C2 BFA1 0974 _______________________________________________ IoT mailing list -- iot@lists.fedoraproject.org To unsubscribe send an email to iot-leave@lists.fedoraproject.org Fedora Code of Conduct: https://getfedora.org/code-of-conduct.html List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines List Archives: https://lists.fedoraproject.org/archives/list/iot@lists.fedoraproject.org