Open Stack

 Hi all,

Anne here - your friendly documentarian!

As the docs PTL, it’s my job to gather input about and make doc tool and
process decisions. This note is the first step: Your responses to this note
give me input to share at the Summit where, hopefully, we will form a
consensus about process and tool changes. About a week after the Summit,
I'll produce a roadmap for changes that we will implement as a community.

A recurring issue that I hope we can solve is barriers to doc
contributions. Leading up to the Summit, I've gathered as much data as I
can about these barriers. We have an awesome doc team and 20 core people on
the team, but only about dozen people write and review the bulk of the
cross-project documentation regularly. It's amazing we've accomplished all
we have with the resources available. We have increased doc contributions
by 10% since the last release, but even so, we must find ways to increase
the doc contributor base.

Remember three and a half years ago? We had nova and swift and a web site
for each. Fast-forward and we now have docs for multiple audiences:

- Contributors who make OpenStack
- Deployers who configure OpenStack
- Operations pros that run OpenStack
- End users who consume and administer OpenStack

But the docs’ contributor base is not growing at the same rate as our
audiences.

Why not? The responses to my recent survey about doc contributions indicate
that the top barriers to docs’ contributions are:

- Tools: DocBook and WADL are difficult
- Doc locations: Lack of knowledge about where docs belong
- Process: Git/gerrit as process
- Subject-matter expertise: People do not have test environments and they
feel that they don't know enough to contribute. Also, 70% of the
respondents to the survey work on or consume OpenStack fewer than 10 hours
a week.

It's not easy to interpret and analyze this data, but I believe we're not
facilitating part-time OpenStack users to write docs and feel confident in
their contributions.

To solve this problem, I want to explore possible changes to our doc tools
and processes. We must engage more doc contributors to spread the doc
creation and maintenance burden.

Tuesday at 12:05 in B304, [1] we're having cross-project
documentation session to discuss this list of requirements for doc tools
and process changes: (See [2] for spreadsheet format.)

Experience:
Solution must be completely open source
Content must be available online
Search engines must be able to index
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, and 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

I want to gather input about these requirements before we discuss
implementation. As far as tools go, some possible solutions are Markdown,
reStructuredText (RST), AsciiDoc, each with its own build framework. I'm
not anticipating a complete migration, but we need to solve these barriers
for certain docs.

Please let me know your thoughts through the OpenStack-docs mailing list if
you cannot attend in person. I am excited to hear your ideas, and I can't
wait to meet a wider audience and serve more doc contributors.

Thanks,
Anne

[1] http://junodesignsummit.sched.org/event/626a1e21babaf30d98973f5eb7402fcf

[2]
https://docs.google.com/spreadsheet/ccc?key=0AhXvn1h0dcyYdFNaQW1OaVNNejZzYlRMZjBnT0pLMVE&usp=sharing
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140507/99cf8a34/attachment.html>