Open Stack

2015-01-20 18:19 Christian Berendt <berendt at b1-systems.de> wrote:
>On 01/20/2015 05:43 PM, Tanja Roth wrote:

>> 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 should keep our bugs in a central place and do not split them across
>multiple vendor specific bug tracking systems. I do not want to have
>(even I already have them) accounts on every bug tracking system and I
>do not want to read tons of duplicate bug reports.

me neither ;)

>
>Also we should not mention bugs in other bug tracking systems in the
>commit messages. Referenced bug reports should be published on
>Launchpad.

understood, this is also what is described as common practice at
https://wiki.openstack.org/wiki/GitCommitMessages#Including_external_references
>
>> 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.
>
>The upstream documents should be independent of specific vendor
>products. It is sufficient to document the installation and usage of
>OpenStack on several distributions (including SLES and openSUSE). It is
>not okay to document the installation or usage of specific products
>like SUSE Cloud, RDO or Mirantis OpenStack.

ok, I see

>
>>    - 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? 
>
>Put them in your knowledgebase and link them in the image guide. Please
>do not start adding SUSE specific documentation to the upstream
>documentation. There is a chapter "Tool support for image creation"
>(http://docs.openstack.org/image-guide/content/ch_creating_images_automatically.html)
>in the image-guide (including SUSE Studio).

linking to a URL from the Image Guide is a good idea, thanks for the
pointer
>
>> 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?         
>
>I would really like to not have distribution specific
>sections/paragraphs in the guides. We have installation guides
>describing the basic installation on several distributions. This should
>be enough. It is hard enought to keep those guides in sync with the
>latest release of OpenStack and the latest release of the
>distributions. 

yep, maintenance/keeping docs up-to-date is always a challenge - I'm
aware of that. 


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)