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 these types of people with these 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
