<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Tue, Jan 20, 2015 at 10:43 AM, Tanja Roth <span dir="ltr"><<a href="mailto:taroth@suse.com" target="_blank">taroth@suse.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Hi Anne, hi all,<br>
<br>
I'm new to this list and I'm a member of the SUSE doc team. I have been<br>
working on the SUSE Cloud End User Guide and Admin User Guide since<br>
some time.<br></blockquote><div><br></div><div>Welcome! I know we appreciated your End User Guide and Admin User Guide in the early days of just getting started with user guides so your work is extremely valuable.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
So far, my direct contributions to the OpenStack project mostly<br>
consisted of (usability) bug reports for Horizon. For the upcoming<br>
releases, we would like to contribute to the OpenStack docs directly,<br>
especially to the Admin User Guide and End User Guide.<br>
<br>
Andreas was so kind to help me set up the OpenStack doc environment last<br>
week. My first contribution was to fix two typos in the Admin User<br>
Guide that I had stumbled across lately. ;)<br>
<br>
I'm currently evaluating how big the diff between the SUSE and the<br>
OpenStack versions of both guides is (and trying to identify snippets<br>
that would perhaps be worth integrating in the OpenStack docs).<br>
<br>
Before moving on, I'd like to get your advice on how to proceed with<br>
the following:<br>
<br>
1) What to do with the doc bug reports we have for both guides in<br>
SUSE-Bugzilla? Should I / do I need to transfer them to launchpad in<br>
order to fix them in the upstream docs?<br></blockquote><div><br></div><div>We've had the same situation at Rackspace, and when we have a bug in both deliverables, we track with two issues, one in each system. Ideally, yes, you'll track in Launchpad in order to get them confirmed in the upstream docs. I say confirmed because in some cases the upstream docs doesn't want to take on technical debt or liability for something that's too specific. </div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
2) What to do in case we need SUSE-specific content in the manuals?<br>
   - For example, we have a bug report asking to specify which guests<br>
     are supported by SUSE Cloud.<br>
<br>
   - We have some sections [1] that contain SUSE-specific instructions<br>
     (e.g how to build images in SUSE Studio and image requirements<br>
     related to that) - what to do with those?<br>
<br>
Andreas told me that profiling (conditional output) for<br>
distribution-specific content is only used in the Installation Guide.<br></blockquote><div><br></div><div>Right, and I was alluding to the scope of what upstream can take on in the answer to your question 1. :) I know that it's great if we can all work on upstream together, and that's the ideal, but we also can't overload the upstream docs with too many "requirements" from multiple groups. So we try to keep the upstream docs simple and as service-oriented as possible, meaning the API-level service.</div><div><br></div><div>For how to build images in SUSE Studio, I think it's okay to put those in the Virtual Machine Image Guide since there is precedence set there already. However the expectation is that you'd continue to do reviews on that content to make sure it remains accurate in a given release. Does that make sense?</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
Should I add SUSE-specific content for the Admin User/End User Guide<br>
simply in a para (or within a section) by saying "For SUSE Linux<br>
Enterprise or openSUSE, do [...]"? If yes, would that be acceptable<br>
also for snippets longer than (let's say) 1-2 sentences?<br></blockquote><div><br></div><div>Thanks for asking in advance! I'd like to keep distro-specific information out of all guides except for the Install Guide since it has been super difficult over the years to maintain. And, this release we're moving towards Sphinx/RST and I don't know how to enable conditional formatting in that platform. </div><div><br></div><div>However, that said I'd like to hear from some others who are maintaining User Guides -- Lana at Rackspace mentioned a user guide and I'm not sure if it's similar to the upstream guide or not. Any thoughts? </div><div><br></div><div>Thanks for asking and thanks helping think through upstream work!</div><div>Anne</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
Thanks in advance!<br>
<br>
BTW, the HowTo instructions [2] and the Documentation conventions [3]<br>
are really helpful for new contributors! But I'm pretty sure that I<br>
will have some more questions to you in the future. If those questions<br>
have already been discussed or answered before, feel free to point me<br>
to the right places (mailing list archives etc.). :)<br>
<br>
-----<br>
[1]<br>
<a href="https://www.suse.com/documentation/suse-cloud4/book_cloud_admin/data/sec_adm_cli_img.html#sec_adm_cli_img_build" target="_blank">https://www.suse.com/documentation/suse-cloud4/book_cloud_admin/data/sec_adm_cli_img.html#sec_adm_cli_img_build</a><br>
<br>
[2] <a href="https://wiki.openstack.org/wiki/Documentation/HowTo" target="_blank">https://wiki.openstack.org/wiki/Documentation/HowTo</a><br>
<br>
[3] <a href="https://wiki.openstack.org/wiki/Documentation/Conventions" target="_blank">https://wiki.openstack.org/wiki/Documentation/Conventions</a><br>
<br>
<br>
Kind regards,<br>
<br>
Tanja Roth, Documentation<br>
SUSE Linux GmbH<br>
<br>
GF: Felix Imendörffer, Jane Smithard, Jennifer Guild, Dilip Upmanyu,<br>
Graham Norton HRB 21284 (AG Nürnberg)<br>
<br>
<br>
<br>
<br>
_______________________________________________<br>
OpenStack-docs mailing list<br>
<a href="mailto:OpenStack-docs@lists.openstack.org">OpenStack-docs@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
</blockquote></div><br><br clear="all"><div><br></div>-- <br><div class="gmail_signature">Anne Gentle<br><a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a></div>
</div></div>