Open Stack

On Tue, 20 Jan 2015 16:37:13 -0600 Anne Gentle
<annegentle at justwriteclick.com> wrote:

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


> > 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.

that is reasonable 
> 
> 
> >
> > 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.

I understand the reasons -- makes sense to me   
> 
> 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?
> 

absolutely :) I'll have a closer look and (depending on the diff) will
see if it makes sense to cover the topic in our knowledgebase or wiki
and just add a pointer (as Christian suggested) or if it boils down to
adding just one or two sentences to the existing section of the guide
directly.   
 
> >
> > 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. 

:) 

At any rate, thanks to you and Christian for the answers and proposals
to help me getting started!

One more question on
https://wiki.openstack.org/wiki/Documentation/HowTo#Editor_Options:

In case of using Oxygen, which settings do you recommend to use in
Preferences > Editor (and Preferences > Editor > XML) for best
results in review.openstack.org?

Cheers,

Tanja Roth, Documentation
SUSE Linux GmbH

GF: Felix Imendörffer, Jane Smithard, Jennifer Guild, Dilip Upmanyu, Graham Norton
HRB 21284 (AG Nürnberg)