Open Stack

Hi Yong Li,

Thanks for getting in touch, and thank you for your work on PCI 
Passthrough!

On 27/09/13 18:00, yongli he wrote:
> 1. new featue and with API, might need upload docs to :
> https://github.com/openstack/openstack-manuals/tree/master/
> and other ?

Yes, if you have made a new feature, we would _love_ documentation :)

The docs team is ready to help for anything: finding the right place, 
editing, formatting, fixing English...

Files in https://github.com/openstack/openstack-manuals/ are actually 
controlled using the normal Gerrit process.

So, since you are familiar with this, if you want you can just edit a 
file and submit a patch to Gerrit as normal. Example patch: 
https://review.openstack.org/#/c/47356/3

There are two hard parts in this process

#1 Finding the right place to put the document

The easiest way to determine which "book" (directory under 
https://github.com/openstack/openstack-manuals/tree/master/doc) to put 
the new document in is to think about what type of person would read it.

Are they a normal user of the cloud --> user-guide
Are they an admin user of the cloud --> user-guide-admin

Are they a cloud administrator that needs help to manage their cloud --> 
admin-guide-cloud

Are they a cloud administrator that wants to check configuration for a 
certain feature --> config-reference

but of course, we can help with this process.

For specific features, you can often make a separate file (look for 
files called section_*.xml)



#2 Learning the DocBook syntax

My secret is: copying an existing file or section and just re-using the 
tags :) It's basically just like HTML. We can help with this too, of course.



> 2. for API docs, do we need summit docs patch?( is it generated from API
> patch?)
API docs, such as the ones that generate the API reference: 
http://api.openstack.org/api-ref.html

are stored in a different repository:
https://github.com/openstack/api-site

(also managed with gerrit)

At the moment, there is only a manual process to update these files. A 
few people are working on an automatic process.

At least the sample files are copied from the source tree to the 
api-site repository, but some manual work is needed to generate a WADL 
specification file. The syntax here is quite hard. Example patch: 
https://review.openstack.org/#/c/48685



I hope that helps!

Please let us know what you need, or any specific cases you would like 
to work on.



Regards,


Tom