Open Stack

On Thu, May 8, 2014 at 9:06 AM, Christian Berendt <berendt at b1-systems.de>wrote:

> On 05/07/2014 10:43 PM, Roger Luethi wrote:
>
>> The people who are qualified to contribute to the docs are usually not
>> non-technical people, but they can't spend hours setting up an environment
>> just to work on docs. IMHO good documentation (or scripts, or VM
>> downloads)
>> that make it easy to create a complete, working environment for testing
>> and
>> building documentation would go a long way towards making contributions
>> easier.
>>
>
> NOTE: The box will soon be available.
>
> I think it's a good idea to have an isolated virtual environment for
> testing and building the documentation.
>

I think this is cool, but to give an idea of some of the comments, I think
people are having trouble testing OpenStack itself to make sure the docs
are accurate. Examples:

"Not sure I have the appropriate expertise."
"...while I know how a system should be *configured*, I know little about
the *install* process."
"...it's often so much work to get a proper patch in because there are
often so many calls that need to be made just to get to the point of where
you want to make the fix. e.g. To create a Neutron port you first need to
create a Net and then a Subnet and there are ton of little bits of info
necessary for those calls. It becomes a non-starter, when you're strapped
for time. The problem is intrinsic to deep APIs so I've got no idea what
could help here."

Also, to clarify, I believe there's more hesitation and doubt around WADL
than DocBook echoed in the survey.

I love this idea of a vagrant box for building docs though, will review!

Thanks,
Anne



>
> Just created an initial Vagrant box that can be used for testing and
> building the documentation inside a virtual system.
>
> It includes Maven and tox. All documentation repositories (+
> openstack-doc-tools) are already pulled (located in /opt/working) and all
> Maven dependencies are downloaded.
>
> There are three scripts available (located in /usr/local/bin) to simplify
> some doings:
>
>   * pull.sh: runs git pull in every repository
>   * fetch.sh: runs mvn dependency:copy-dependencies in every directory
> including a pom.xml
>   * build.sh: builds a specified document in a specified repository
>
> For example to build the document admin-guide-cloud in the repository
> openstack-manuals run build.sh openstack-manuals admin-guide-cloud.
>
> The box has a directory "/opt/working" that's synced to the local
> directory working on the workstation. This way it's possible to edit and
> commit the files using the already available toolchain on the workstation
> and to test and build the documents inside the virtual system.
>
> As a nit port 8080 on the workstation is forwarded to port 80 on the
> virtual system. Port 80 simply serves the files located in /opt/working
> using Nginx. To view the local-files.html simply go to
> http://localhost:8080/openstack-manuals/doc/.
>
> Christian.
>
> --
> Christian Berendt
> Cloud Computing Solution Architect
> Mail: berendt at b1-systems.de
>
> B1 Systems GmbH
> Osterfeldstraße 7 / 85088 Vohburg / http://www.b1-systems.de
> GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537
>
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140508/51b20b14/attachment.html>