Documenting your work¶

Where to add documentation?¶

Important things to note¶

• When implementing a new feature, use appropriate Commit Message Tags (Using Commit Message Tags in Manila).
• Using the DocImpact flag in particular will create a [doc] bug under the manila project in launchpad. When your code patch merges, assign this bug to yourself and track your documentation changes with it.
• When writing documentation outside of manila, use either a commit message header that includes the word Manila or set the topic of the change-set to manila-docs. This will make it easy for manila reviewers to find your patches to aid with a technical content review.
• When writing documentation in user/admin/config/api/install guides, always refer to the project with its service name: Shared File Systems service and not the service type (share) or the project name (manila).
• Follow documentation styles prescribed in the OpenStack Documentation Contributor Guide. Pay heed to the RST formatting conventions and Writing style.
• Use CamelCase to spell out OpenStack and sentence casing to spell out service types, ex: Shared File Systems service and lower case to spell out project names, ex: manila (except when the project name is in the beginning of a sentence or a title).
• ALWAYS use a first party driver when documenting a feature in the user or administrator guides. Provide cross-references to configuration reference sections to lead readers to detailed setup instructions for these drivers.
• The manila developer reference, the OpenStack user guide, administrator reference, API reference and security guide are always current, i.e, get built with every commit in the respective codebase. Therefore, documentation added here need not be backported to previous releases.
• You may backport changes to some documentation such as the configuration reference and the installation guide. Refer to the instructions here.
• Important “documentation” that isn’t really documentation - specs and release notes are NOT documentation. A specification document is written to initiate a dialogue and gather feedback regarding the design of a feature. Neither developers nor users will regard a specification document as official documentation after a feature has been implemented. Release notes (Release Notes) allow for gathering release summaries and they are not used to understand, configure, use or troubleshoot any manila feature.
• Less is not more, more is more - Always add detail when possible. The health and maturity of our community is reflected in our documentation.