Open Stack

On Tue, Jan 20, 2015 at 10:43 AM, Tanja Roth <taroth at suse.com> wrote:

> Hi Anne, hi all,
>
> I'm new to this list and I'm a member of the SUSE doc team. I have been
> working on the SUSE Cloud End User Guide and Admin User Guide since
> some time.
>

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.


>
> So far, my direct contributions to the OpenStack project mostly
> consisted of (usability) bug reports for Horizon. For the upcoming
> releases, we would like to contribute to the OpenStack docs directly,
> especially to the Admin User Guide and End User Guide.
>
> Andreas was so kind to help me set up the OpenStack doc environment last
> week. My first contribution was to fix two typos in the Admin User
> Guide that I had stumbled across lately. ;)
>
> I'm currently evaluating how big the diff between the SUSE and the
> OpenStack versions of both guides is (and trying to identify snippets
> that would perhaps be worth integrating in the OpenStack docs).
>
> Before moving on, I'd like to get your advice on how to proceed with
> the following:
>
> 1) What to do with the doc bug reports we have for both guides in
> SUSE-Bugzilla? Should I / do I need to transfer them to launchpad in
> order to fix them in the upstream docs?
>

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.


>
> 2) What to do in case we need SUSE-specific content in the manuals?
>    - For example, we have a bug report asking to specify which guests
>      are supported by SUSE Cloud.
>
>    - We have some sections [1] that contain SUSE-specific instructions
>      (e.g how to build images in SUSE Studio and image requirements
>      related to that) - what to do with those?
>
> Andreas told me that profiling (conditional output) for
> distribution-specific content is only used in the Installation Guide.
>

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.

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?


>
> Should I add SUSE-specific content for the Admin User/End User Guide
> simply in a para (or within a section) by saying "For SUSE Linux
> Enterprise or openSUSE, do [...]"? If yes, would that be acceptable
> also for snippets longer than (let's say) 1-2 sentences?
>

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.

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?

Thanks for asking and thanks helping think through upstream work!
Anne


>
> Thanks in advance!
>
> BTW, the HowTo instructions [2] and the Documentation conventions [3]
> are really helpful for new contributors! But I'm pretty sure that I
> will have some more questions to you in the future. If those questions
> have already been discussed or answered before, feel free to point me
> to the right places (mailing list archives etc.). :)
>
> -----
> [1]
>
> https://www.suse.com/documentation/suse-cloud4/book_cloud_admin/data/sec_adm_cli_img.html#sec_adm_cli_img_build
>
> [2] https://wiki.openstack.org/wiki/Documentation/HowTo
>
> [3] https://wiki.openstack.org/wiki/Documentation/Conventions
>
>
> Kind regards,
>
> Tanja Roth, Documentation
> SUSE Linux GmbH
>
> GF: Felix Imendörffer, Jane Smithard, Jennifer Guild, Dilip Upmanyu,
> Graham Norton HRB 21284 (AG Nürnberg)
>
>
>
>
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>



-- 
Anne Gentle
annegentle at justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20150120/89a35f8c/attachment.html>