Jump to: navigation, search

Difference between revisions of "Documentation"

m (PDF for Project Docs - Community Goal)
(20 intermediate revisions by 13 users not shown)
Line 10: Line 10:
 
-->
 
-->
  
The focus here is the creation, maintenance and organization of the OpenStack documentation found at the http://docs.openstack.org site and the wiki.openstack.org site. While the Docs team helps create a good framework, it's the entire OpenStack community -- and especially contributors like you -- that provides the expert content and corrections for the documentation.
+
The focus here is the creation, maintenance and organization of the OpenStack documentation found at the http://docs.openstack.org site. While the Docs team helps create a good framework, it's the entire OpenStack community -- and especially contributors like you -- that provides the expert content and corrections for the documentation.
  
 
{| border="1" cellpadding="2" cellspacing="0" class="wikitable"
 
{| border="1" cellpadding="2" cellspacing="0" class="wikitable"
Line 26: Line 26:
 
|-
 
|-
 
| Source code
 
| Source code
| openstack-manuals; api-site - see [https://wiki.openstack.org/wiki/Documentation/Builds doc builds] for full list
+
| openstack-manuals; api-site
 
|-
 
|-
 
| Bug tracker
 
| Bug tracker
Line 34: Line 34:
 
| http://blueprints.launchpad.net/openstack-manuals
 
| http://blueprints.launchpad.net/openstack-manuals
 
|-
 
|-
| Developer doc
+
| Contributor doc
|[[Documentation/HowTo|Documentation HowTo]]
+
| [https://docs.openstack.org/doc-contrib-guide/ Documentation Contributor Guide]
 
|-
 
|-
 
| Current PTL
 
| Current PTL
| Lana Brindley -  openstack(at)lanabrindley(dot)com, IRC: loquacities
+
| See https://governance.openstack.org/tc/reference/projects/documentation.html
 
|-
 
|-
 
| Meetings
 
| Meetings
Line 47: Line 47:
 
|-
 
|-
 
| Mailing list
 
| Mailing list
| [http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs OpenStack documentation mailing list]
+
| [http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev OpenStack development mailing list] (use the [docs] tag in subject)
 
|-
 
|-
 
|}
 
|}
Line 58: Line 58:
  
 
== Source repositories ==
 
== Source repositories ==
Doc source is on GitHub. Everyone can propose changes to docs, see [[Documentation/HowTo]]. Here are the repositories that build to docs.openstack.org.  
+
Doc source is mirrored on GitHub. Everyone can propose changes to docs, see [[Documentation/HowTo]]. Here are the repositories that build to docs.openstack.org.  
  
For a complete listing of which docs are built, including details about source and target locations, see [[Documentation/Builds]].
+
For a list of source repositories, see [https://governance.openstack.org/tc/reference/projects/documentation.html#deliverables Deliverables].
  
* http://git.openstack.org/cgit/openstack/openstack-manuals - Installation, administration, configuration, architecture design guide and user guides
+
For more information on which docs are published, see [https://docs.openstack.org/contributor-guide/blueprints-and-specs.html Content specification].
* http://git.openstack.org/cgit/openstack/api-site -  API Quick Start and API Complete Reference page
 
* http://git.openstack.org/cgit/openstack/operations-guide - Operations Guide
 
* http://git.openstack.org/cgit/openstack/openstack-doc-tools - Documentation Tools
 
* http://git.openstack.org/cgit/openstack/openstackdocstheme - Sphinx theme for RST documentation
 
* http://git.openstack.org/cgit/openstack/security-doc - Security Guide
 
* http://git.openstack.org/cgit/openstack/training-guides - Training Guides
 
* http://git.openstack.org/cgit/openstack/ha-guide - High Availability Guide
 
 
 
== Development ==
 
 
 
These guides are available and sourced in .rst files in /doc/source/ if you want to work on them:
 
* [http://docs.openstack.org/developer/swift/development_guidelines.html OpenStack Object Storage (Swift) Development Guidelines]
 
* [http://docs.openstack.org/developer/nova/devref/index.html OpenStack Compute (Nova) Developer Guide]
 
* [http://docs.openstack.org/developer/glance/ OpenStack Image Service (Glance) Developer Docs]
 
* [http://docs.openstack.org/developer/keystone/ OpenStack Identity Service (Keystone) Developer Docs]
 
* [http://docs.openstack.org/developer/neutron/ OpenStack Networking (Neutron) Developer Docs]
 
* [http://docs.openstack.org/developer/cinder/ OpenStack Block Storage (Cinder) Developer Docs]<br />
 
 
 
 
 
Ideally the above content is geared towards developers.
 
 
 
The content at docs.openstack.org is for OpenStack administrators and application developers.
 
  
 
== Releases ==
 
== Releases ==
 
Lists current development release and past releases, with links to downloads and release notes (what's new and what's changed in each release as well as known issues and potential workarounds)
 
Lists current development release and past releases, with links to downloads and release notes (what's new and what's changed in each release as well as known issues and potential workarounds)
  
* [[Releases]]
+
* [https://releases.openstack.org/ OpenStack Releases]
  
 
== Support ==
 
== Support ==
Line 108: Line 86:
 
How to contribute code to [http://www.openstack.org OpenStack] or develop using the OpenStack projects.
 
How to contribute code to [http://www.openstack.org OpenStack] or develop using the OpenStack projects.
  
 +
* [http://docs.openstack.org/infra/manual/developers.html Developer's Guide in the Infra Manual]
 
* [[HowToContribute|How to Contribute ]]
 
* [[HowToContribute|How to Contribute ]]
 
* Sign the [http://docs.openstack.org/infra/manual/developers.html#account-setup Contributor agreement]
 
* Sign the [http://docs.openstack.org/infra/manual/developers.html#account-setup Contributor agreement]
 
* [[BasicDesignTenets|Design Tenets]]
 
* [[BasicDesignTenets|Design Tenets]]
* [[ReleaseCycle|Explanation of the Release cycle ]]
+
* [http://docs.openstack.org/project-team-guide/ Project Team Guide]
 
* [[CodingStandards|Coding Standards]]
 
* [[CodingStandards|Coding Standards]]
 
* [[GettingTheCode|Getting the Code]]
 
* [[GettingTheCode|Getting the Code]]
Line 123: Line 102:
  
 
= Writing documentation =
 
= Writing documentation =
 +
 +
First, read the [http://docs.openstack.org/contributor-guide/ Documentation Contributor Guide].
  
 
* [[Documentation/HowTo|How to contribute to the documentation]]  
 
* [[Documentation/HowTo|How to contribute to the documentation]]  
 
* [[Documentation/Conventions|Conventions to follow when writing documentation]]
 
* [[Documentation/Conventions|Conventions to follow when writing documentation]]
* [[Documentation/Builds|Documentation build information]]
 
 
* [[Documentation/Migrate|DocBook to RST Migrations]]
 
* [[Documentation/Migrate|DocBook to RST Migrations]]
 
* [[Documentation/DocImpact|DocImpact]]
 
* [[Documentation/DocImpact|DocImpact]]
Line 133: Line 113:
 
* [http://docs.rackspace.com/writers-guide/content Rackspace's Writers Guide]
 
* [http://docs.rackspace.com/writers-guide/content Rackspace's Writers Guide]
 
* [[Documentation/ReviewGuidelines|Review Guidelines]]
 
* [[Documentation/ReviewGuidelines|Review Guidelines]]
* [[JunoDocTesting]]
+
* [[Documentation/MitakaDocTesting|Mitaka Documentation Testing - Installation Guide and Configuration Reference]]
* [[KiloDocTesting]]
 
 
* [[Documentation/Release|How to make a documentation release]]
 
* [[Documentation/Release|How to make a documentation release]]
 +
* [[Documentation/UserAnalysis|Documentation user analysis]]
 +
* [[Documentation/PikeDocTesting]]
  
=== Admin access to to the documentation site ===
+
= Admin access to to the documentation site =
  
 
There are some areas where only trusted infrastructure or doc team members have access to configure or manage part of the documentation site. Examples include:
 
There are some areas where only trusted infrastructure or doc team members have access to configure or manage part of the documentation site. Examples include:
Line 151: Line 132:
  
 
Currently the infrastructure core team and Docs PTL has access to the FTP credentials. The Docs PTL has access to the Google CSE information and the Google Analytics account information. The Docs PTL can grant access to the shared Google information. The infrastructure core team can grant access to the FTP credentials.
 
Currently the infrastructure core team and Docs PTL has access to the FTP credentials. The Docs PTL has access to the Google CSE information and the Google Analytics account information. The Docs PTL can grant access to the shared Google information. The infrastructure core team can grant access to the FTP credentials.
 +
 +
= PDF for Project Docs - Community Goal =
 +
 +
{| border="1" cellpadding="2" cellspacing="3" class="wikitable"
 +
|-
 +
| '''Full name (IRC nickname)'''
 +
| '''Project name'''
 +
| '''Test status'''
 +
|-
 +
| Akihiro Motoki (amotoki)
 +
| Neutron
 +
|  TBD
 +
|-
 +
|Donny Davis
 +
| Nova
 +
|  TBD
 +
|-
 +
|Michael Johnson (johnsom)
 +
| Octavia
 +
|  TBD
 +
|-
 +
|Luigi Toscano (tosky)
 +
| Sahara
 +
|  TBD
 +
|-
 +
|Bogdan Dobrelya (bogdando)
 +
| TripleO
 +
|  TBD
 +
|-
 +
|
 +
|
 +
|
 +
|-
 +
|}
  
 
= References =
 
= References =

Revision as of 09:44, 25 June 2019


The focus here is the creation, maintenance and organization of the OpenStack documentation found at the http://docs.openstack.org site. While the Docs team helps create a good framework, it's the entire OpenStack community -- and especially contributors like you -- that provides the expert content and corrections for the documentation.

OpenStack Documentation Project Team
Full name OpenStack Documentation
Code name None
Status Related
Source code openstack-manuals; api-site
Bug tracker http://bugs.launchpad.net/openstack-manuals and http://bugs.launchpad.net/openstack-api-site
Blueprints http://blueprints.launchpad.net/openstack-manuals
Contributor doc Documentation Contributor Guide
Current PTL See https://governance.openstack.org/tc/reference/projects/documentation.html
Meetings Documentation team meeting
IRC channel #openstack-doc on Freenode (more about OpenStack on IRC)
Mailing list OpenStack development mailing list (use the [docs] tag in subject)

OpenStack documentation

Published docs and their location

The public interface to all documentation is the docs.openstack.org web site. It contains continuously updated manuals. If you like to edit one of these, see Documentation source and target locations for a list of documents and their source repositories.

Source repositories

Doc source is mirrored on GitHub. Everyone can propose changes to docs, see Documentation/HowTo. Here are the repositories that build to docs.openstack.org.

For a list of source repositories, see Deliverables.

For more information on which docs are published, see Content specification.

Releases

Lists current development release and past releases, with links to downloads and release notes (what's new and what's changed in each release as well as known issues and potential workarounds)

Support

How to find or ask for support.

Glossary

  • Glossary - Contains terms that are our definitions for OpenStack, cloud computing, and open source.

Project documentation

This is general information about OpenStack.

Development

How to contribute code to OpenStack or develop using the OpenStack projects.

Launchpad reference

How we use Launchpad to track features, bugs and releases.

Writing documentation

First, read the Documentation Contributor Guide.

Admin access to to the documentation site

There are some areas where only trusted infrastructure or doc team members have access to configure or manage part of the documentation site. Examples include:

  • FTP credentials to the Cloud Sites that houses the files for docs.openstack.org and developer.openstack.org.
  • Google Custom Search Engine (CSE) configuration.
  • Google Analytics account information and configuration.

For these shared identities, we use the following process to ensure limited access to the information that grants access.

  • At the Summit or another in-person meeting, ensure we verify identities with IDs similar to a GPG party.
  • With those identities and shared trust in place, create a server with a place to store the account information.
  • Enable access to the shared account info by granting access to the server.

Currently the infrastructure core team and Docs PTL has access to the FTP credentials. The Docs PTL has access to the Google CSE information and the Google Analytics account information. The Docs PTL can grant access to the shared Google information. The infrastructure core team can grant access to the FTP credentials.

PDF for Project Docs - Community Goal

Full name (IRC nickname) Project name Test status
Akihiro Motoki (amotoki) Neutron TBD
Donny Davis Nova TBD
Michael Johnson (johnsom) Octavia TBD
Luigi Toscano (tosky) Sahara TBD
Bogdan Dobrelya (bogdando) TripleO TBD

References

There are many additional publications about OpenStack by third party publishers. Please search for them on your favorite bookseller site.