Rip. Shred. Tear. Let’s gather up the obstacles to documentation contribution and tear them down one by one. I’ve designed a survey with the help of the OpenStack docs team to determine blockers for docs contributions. If you’ve contributed to OpenStack, please fill it out here:
https://docs.google.com/forms/d/136-BssH-OxjVo8vNoOD-gW4x8fDFpvixbgCfeV1w_do/viewform
I want to use this survey to avoid shouting opinions and instead make sure we gather data first. This survey helps us find the biggest barriers so that we can build the best collaboration systems for documentation on OpenStack. Here are the obstacles culled from discussions in the community:
- The git/gerrit workflow isn’t in my normal work environment
- The DocBook and WADL (XML source) tools are not in my normal work environment
- My team or manager doesn’t value documentation so we don’t make time for it
- Every time I want to contribute to docs, I can’t figure out where to put the information I know
- When I’ve tried to patch documentation, the review process was difficult or took too long
- When I’ve contributed to docs, developers changed things without concern for docs, so my efforts were wasted
- Testing doc patches requires an OpenStack environment I don’t have set up or access to in a lab
- I think someone else should write the documentation, not me
- I would only contribute documentation if I were paid to do so
Based on the input from the survey, I want to gather requirements for doc collaboration.
We have different docs for different audiences:
- cross-project docs for deploy/install/config: openstack-manuals
- API docs references, standards: api-site and others
These are written with the git/gerrit method. I want to talk about standing up a new docs site that serves our requirements:
Experience:
Solution must be completely open source
Content must be available online
Content must be indexable by search engines
Content must be searchable
Content should be easily cross-linked by topic and type (priority:low)
Enable comments, ratings, and analytics (or ask.openstack.org integration) (priority:low)
Distribution:
Readers must get versions of technical content specific to version of product
Modular authoring of content
Graphic and text content should be stored as files, not in a database
Consumers must get technical content in PDF, html, video, audio
Workflow for review and approval prior to publishing content
Authoring:
Content must be re-usable across authors and personas (Single source)
Must support many content authors with multiple authoring tools
Existing content must migrate smoothly
All content versions need to be comparable (diff) across versions
Content must be organizationally segregated based on user personas
Draft content must be reviewable in HTML
Link maintenance – Links must update with little manual maintenance to avoid broken links and link validation
Please take the survey and make your voice heard! Also please join us at a cross-project session at the OpenStack Summit to discuss doc contributions. We’ll go over the results there. The survey is open until the first week of May.