Open Stack

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 29/04/15 01:47, Michael Klishin wrote:
> On 28 April 2015 at 17:24:56, Anne Gentle (annegentle at justwriteclick.com) wrote:
>> The entry point for documentation is
>> https://wiki.openstack.org/wiki/Documentation/HowTo.
> 
> Thank you.
>

Hi Michael, and welcome :)


>> We will discuss in
>> Vancouver on the summit how to improve the experience for newcomers  
>> to
>> the documentation.
> 
> By the way, I attend it, including the design summit. Do I need to RSVP somewhere to join that session? :)

You don't need to specifically RSVP, just turn up to the session. I'm
still finalising the schedule, but should have something up by the end
of this week. Keep an eye on this mailing list for more info soon.

> 
>>> As far as I understand, OpenStack Kilo is about to ship. Does  
>> this mean we can only contribute
>>> documentation improvements for the release after it? Are there  
>> maintenance releases that doc improvements
>>> could go into? If so, how is this reflected in repository branches?  
>>  
>> In a few days there will be a stable/kilo branch. It is possible  
>> to
>> backport changes from the current state of the repository to  
>> the stable
>> branches. We do not have to wait for the regular maintaince release  
>> to
>> publish changes there.
> 
> Perfect.
> 
>>> Should the changes we propose be discussed on this list or in  
>> GitHub issues [1]?
>>  
>> On this list or on launchpad. We do not use the Github issues.
>>  
>> https://launchpad.net/openstack-manuals
> 
> Got it. I suspect developer docs cover how patches are submitted.

The best resource for this is the HowTo that Christian mentioned:
https://wiki.openstack.org/wiki/Documentation/HowTo

You can also ask for assistance either on this mailing list, or on IRC
in #openstack-doc on freenode.

> 
>>> Finally, we are considering adding a doc guide dedicated to  
>> OpenStack on rabbitmq.com (we have one for EC2,
>>> for instance). Note that we are not looking
>>> to replace what's on docs.openstack.org, only provide a guide  
>> that can go into more details.
>>> Does this sound like a good idea to the OpenStack community?  
>> Should we keep everything on docs.openstack.org?
>>> Would it be OK if we link to rabbitmq.com guides in any changes  
>> we contribute? I don't think OpenStack Juno
>>> docs have a lot of external links: is that by design?
>>  
>> I think it depends. It would be nice to have a working minimal guide  
>> for
>> RabbitMQ inside the OpenStack documentation (as used at the  
>> moment in
>> the installation guides).
> 
> I agree.
> 
>> Do you mean this EC2 guide: http://www.rabbitmq.com/ec2.html  
>> ?
> 
> That's the one, yes.
> 
>> I think
>> such guides should be directly published on rabbitmq.com. I  
>> can assist
>> while writing a guide for OpenStack.
> 
> We are leaning towards this, too: have a minimalistic guide on openstack.org
> and link to relevant parts on rabbitmq.com, then introduce a separate guide for OpenStack
> users that we'll maintain.


I can only reiterate what Anne already said: we we are extremely
resource constrained, and I'm very wary of taking on more maintenance
load than we can handle. We would love to have your contributions to the
documentation, but new or expanded documentation needs to be very
carefully considered before it can be included for Liberty. I'm happy to
continue this conversation with you during the Liberty planning process
though, and would love to go through more details with you in Vancouver.

> 
> Thank you, folks. This has been very helpful. We'll get to work on the patches :)

Great! Please let us know if you have any trouble :)

Lana

- -- 
Lana Brindley
Technical Writer
Rackspace Cloud Builders Australia
http://lanabrindley.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1

iQEcBAEBAgAGBQJVQBZvAAoJELppzVb4+KUyC3gH/RO5+sIQjo/HAOYda4y58eo4
9fQT3uWXMfHZZKo7DoCnsiOP/7qdqLdLzmVaKGW7xFei7hyOuhqKm11qV1psYr4N
8n/QsztDKE8BTr4kHas0gcJurHQLQMM+3NTv3EsykREH1nHmRhNwRRQlfPpq8e7p
bNLJcBJGsIDvRuuJgACwANpn0lxHLUdr4xWF9q9q9QnHX44KQJrUbcJjg2ky6XLT
z+PTtOUZLR1TE0q1t6KdGzxBmAY7Fg3vMhUMeUUKw5qHGmOP3M25OPNGQ9mybMBR
ixyLU3Y70mBM5GGEmn7rPSVC3PdYVOdJoAZDLp7g8nhYg/jvyTBvW0wc3OpA0/o=
=gtMG
-----END PGP SIGNATURE-----