Jump to: navigation, search

Difference between revisions of "Documentation"

(Development)
 
(123 intermediate revisions by 26 users not shown)
Line 1: Line 1:
__TOC__
+
{{OpenStack_Documentation_Navbar}}
= [[OpenStack]] software documentation =
 
  
Documentation is community-oriented and available for different audiences on several websites - this wiki is for fast, changing documentation, the developer documentation for the projects is on [http://nova.openstack.org/  nova.openstack.org], [http://swift.openstack.org/ swift.openstack.org], [http://keystone.openstack.org/ keystone.openstack.org], and [http://glance.openstack.org  glance.openstack.org]. For official documentation, see [http://docs.openstack.org  docs.openstack.org]. To log a bug against the documentation, go to http://bugs.launchpad.net/openstack-manuals.
+
<!--
 +
{| style="color:#000000; border:solid 1px #A8A8A8; padding:0.5em; margin:0.5em 0; background-color:#FFFFFF;font-size:95%; vertical-align:middle;"
 +
| style="padding:1em;width: 40px" | [[File:Drowning_noun_project_4285.svg|40px]]
 +
| '''Join Our Bug Day'''
 +
We need your help.
 +
Join our [[Documentation/BugDay|Documentation Bug Day]] on Tuesday 9th September, 2014.
 +
|}
 +
-->
  
There's also an [http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs OpenStack documentation mailing list].
+
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.
  
<<Columns(2, start)>>
+
{| border="1" cellpadding="2" cellspacing="0" class="wikitable"
 +
|-
 +
!colspan="2"|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
 +
| [https://docs.openstack.org/doc-contrib-guide/ Documentation Contributor Guide]
 +
|-
 +
| Current SIG Chair
 +
| See Technical Writing SIG at https://governance.openstack.org/sigs/
 +
|-
 +
| Meetings
 +
| [[Meetings/DocTeamMeeting|Documentation team meeting]]
 +
|-
 +
| IRC channel
 +
| #openstack-doc on OFTC ([https://wiki.openstack.org/wiki/IRC more about OpenStack on IRC])
 +
|-
 +
| Mailing list
 +
| [http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev OpenStack development mailing list] (use the [docs] tag in subject)
 +
|-
 +
|}
  
= [[OpenStack]] Manuals =
+
= OpenStack documentation =
  
== [[OpenStack]] APIs ==
+
== Published docs and their location ==
  
* http://api.openstack.org
+
The public interface to all documentation is the [http://docs.openstack.org/ docs.openstack.org] web site. It contains continuously updated manuals. If you like to edit one of these, see [[Documentation/Builds#Documentation_source_and_target_locations|Documentation source and target locations]] for a list of documents and their source repositories.
* [http://docs.openstack.org/api/quick-start/content/  OpenStack API Quick Start]
 
* [http://docs.openstack.org/api/openstack-compute/programmer/content/  Programming OpenStack Compute API with Shell and Python ]
 
* [http://docs.openstack.org/api/openstack-compute/2/content/  OpenStack Compute Developer Guide API 2 ]
 
* [http://docs.openstack.org/api/openstack-image-service/1.0/content/  OpenStack Image Service Developer Guide API 1.0]
 
* [http://docs.openstack.org/api/openstack-object-storage/1.0/content/  OpenStack Object Storage Developer Guide API 1.0]
 
* [http://docs.openstack.org/api/openstack-identity-service/2.0/content/  OpenStack Identity Service Developer Guide API 2.0]
 
* [http://docs.openstack.org/api/openstack-network/2.0/content/  Openstack Network Service Developer Guide API 2.0]
 
  
== Administration ==
+
== 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.
  
* OpenStack Compute Administration Manual [http://docs.openstack.org/trunk/openstack-compute/admin/content/  html] [http://docs.openstack.org/trunk/openstack-compute/admin/os-compute-adminguide-trunk.pdf  pdf]
+
For a list of source repositories, see [https://governance.openstack.org/tc/reference/projects/documentation.html#deliverables Deliverables].
* OpenStack Object Storage Administration Manual [http://docs.openstack.org/trunk/openstack-object-storage/admin/content/  html] [http://docs.openstack.org/trunk/openstack-object-storage/admin/os-objectstorage-adminguide-trunk.pdf  pdf]
 
* OpenStack Network Administration Manual (Quantum) [http://docs.openstack.org/trunk/openstack-network/admin/content/  html] [http://docs.openstack.org/trunk/openstack-network/admin/quantum-admin-guide-trunk.pdf  pdf]
 
  
== Source Repositories ==
+
For more information on which docs are published, see [https://docs.openstack.org/contributor-guide/blueprints-and-specs.html Content specification].
Doc source is on GitHub. Everyone can propose merge to docs. Here are the repositories that build to docs.openstack.org.
 
* http://github.com/openstack/openstack-manuals
 
* http://github.com/openstack/compute-api
 
* http://github.com/openstack/identity-api
 
* http://github.com/openstack/image-api
 
* http://github.com/openstack/object-api
 
* http://github.com/openstack/netconn-api
 
 
 
== Development ==
 
 
 
These guides are available and sourced in .rst files in /doc/source/ if you want to work on them:
 
* [http://swift.openstack.org/development_guidelines.html   OpenStack Object Storage (Swift) Development Guidelines]
 
* [http://nova.openstack.org/devref/index.html  OpenStack Compute (Nova) Developer Guide ]
 
* [http://glance.openstack.org/#developer-docs  OpenStack Image Service (Glance) Developer Docs ]
 
* [http://keystone.openstack.org/  OpenStack Identity Service (Keystone) Developer Docs ]
 
* [http://quantum.openstack.org/  OpenStack Network Service (Quantum) Developer Docs ]
 
 
 
Ideally the content on the above sites is geared towards developers, and docs.openstack.org is for developer consumers of the ReST API and OpenStack administrators.  
 
  
 
== 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]
 
 
== Installation ==
 
How to install either Swift or Nova.
 
 
 
* [[[SwiftInstall|| Object Storage (Swift) Installation ]]]
 
* [[InstallInstructions/Nova | Compute (Nova) Installation ]]
 
  
 
== Support ==
 
== Support ==
Line 63: Line 74:
 
* [[MailingLists|Mailing Lists]]
 
* [[MailingLists|Mailing Lists]]
 
* [http://www.openstack.org/projects/openstack-faq/ OpenStack Community Q & A]
 
* [http://www.openstack.org/projects/openstack-faq/ OpenStack Community Q & A]
* [https://answers.launchpad.net/openstack Launchpad Answers]
+
* [https://ask.openstack.org Ask OpenStack]
  
 
== Glossary ==
 
== Glossary ==
* [[Glossary]] - Contains terms that are our definitions for OpenStack, cloud computing, and open source.
+
* [http://docs.openstack.org/glossary/content/glossary.html Glossary] - Contains terms that are our definitions for OpenStack, cloud computing, and open source.
<<Columns(2)>>
+
 
 
= Project documentation =
 
= Project documentation =
 +
 +
This is general information about OpenStack.
  
 
== Development ==
 
== Development ==
How to contribute code to [[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 [[CLA|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]]
* [[LifeWithBzrAndLaunchpad|Learning bzr and Launchpad ]]
+
* [[GettingTheCode|Getting the Code]]
* [[GettingTheCode|Getting the Code (using Launchpad and bzr)]]
 
  
 
== Launchpad reference ==
 
== Launchpad reference ==
Line 88: Line 101:
 
* [[LaunchpadGroups|Launchpad groups]]
 
* [[LaunchpadGroups|Launchpad groups]]
  
== 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/Conventions|Conventions to follow when writing documentation]]
 +
* [[Documentation/Migrate|DocBook to RST Migrations]]
 +
* [[Documentation/DocImpact|DocImpact]]
 +
* [[Documentation/Troubleshooting|Troubleshooting doc builds]]
 +
* [[Documentation/DocComments|Comments on Documentation]]
 +
* [http://docs.rackspace.com/writers-guide/content Rackspace's Writers Guide]
 +
* [[Documentation/ReviewGuidelines|Review Guidelines]]
 +
* [[Documentation/MitakaDocTesting|Mitaka Documentation Testing - Installation Guide and Configuration Reference]]
 +
* [[Documentation/Release|How to make a documentation release]]
 +
* [[Documentation/UserAnalysis|Documentation user analysis]]
 +
* [[Documentation/PikeDocTesting]]
 +
 
 +
= 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 =
 +
 
 +
'''Technical Committee champion:''' Alexandra Settle (asettle)
 +
 
 +
'''Community goal:''' https://governance.openstack.org/tc/goals/train/pdf-doc-generation.html
 +
 
 +
During the Ocata cycle, the OpenStack-manuals, infra, and translations team worked together to enable the generation of PDF doc files from rst-based guide documents.
 +
This change generated a single downloadable PDF per Sphinx project. This means that each “book” built from a single Sphinx project could generate a PDF, allowing users
 +
who want to see documents offline the ability to do so.
 +
 
 +
The work was completed at the end of the Ocata release, but was never implemented within the project repositories. This means that our users are only able to download
 +
PDF documents for the Installation Guide, the Contributor Guide, and the Image Guide, limiting the scope for our offline users.
 +
This goal proposes we enable support across the project repositories to further our goal of being an accessible open source community.
 +
 
 +
 
 +
'''Tracking Etherpad:''' https://etherpad.openstack.org/p/train-pdf-support-goal
 +
 
 +
'''Etherpad to track common issues:''' https://etherpad.openstack.org/p/pdf-goal-train-common-problems
 +
 
 +
'''Storyboard:''' https://storyboard.openstack.org/#!/story/list?tags=pdf-doc-enabled
 +
 
 +
 
 +
 
 +
 
 +
'''NOTE: Below is no longer in use'''
 +
 
 +
{| border="1" cellpadding="2" cellspacing="3" class="wikitable"
 +
|-
 +
| '''Full name (IRC nickname)'''
 +
| '''Project name'''
 +
| '''Tracking etherpad'''
 +
| '''Test status'''
 +
|-
 +
| Akihiro Motoki (amotoki)
 +
| Neutron
 +
| https://etherpad.openstack.org/p/pdf-goal-train-neutron
 +
|  TBD
 +
|-
 +
|Donny Davis
 +
| Nova
 +
| https://etherpad.openstack.org/p/pdf-goal-train-nova
 +
|  TBD
 +
|-
 +
|Michael Johnson (johnsom)
 +
| Octavia
 +
| https://etherpad.openstack.org/p/pdf-goal-train-octavia
 +
|  TBD
 +
|-
 +
|Luigi Toscano (tosky)
 +
| Sahara
 +
| https://etherpad.openstack.org/p/pdf-goal-train-sahara
 +
|  TBD
 +
|-
 +
|Bogdan Dobrelya (bogdando)
 +
| TripleO
 +
| https://etherpad.openstack.org/p/pdf-goal-train-tripleo
 +
|  TBD
 +
|-
 +
|}
  
* [[Documentation/HowTo | How to contribute to the documentation]]
+
= References =
* [[Documentation/Conventions| DocBook markup conventions]]
 
  
<<Columns(2, end)>>
+
There are many additional publications about OpenStack by third party publishers. Please search for them on your favorite bookseller site.
  
 
----
 
----
 
[[Category:HowTo]]
 
[[Category:HowTo]]
 +
[[Category:Documentation]]
 +
[[Category: Horizontal_Team]]

Latest revision as of 15:25, 1 October 2021


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 SIG Chair See Technical Writing SIG at https://governance.openstack.org/sigs/
Meetings Documentation team meeting
IRC channel #openstack-doc on OFTC (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

Technical Committee champion: Alexandra Settle (asettle)

Community goal: https://governance.openstack.org/tc/goals/train/pdf-doc-generation.html

During the Ocata cycle, the OpenStack-manuals, infra, and translations team worked together to enable the generation of PDF doc files from rst-based guide documents. This change generated a single downloadable PDF per Sphinx project. This means that each “book” built from a single Sphinx project could generate a PDF, allowing users who want to see documents offline the ability to do so.

The work was completed at the end of the Ocata release, but was never implemented within the project repositories. This means that our users are only able to download PDF documents for the Installation Guide, the Contributor Guide, and the Image Guide, limiting the scope for our offline users. This goal proposes we enable support across the project repositories to further our goal of being an accessible open source community.


Tracking Etherpad: https://etherpad.openstack.org/p/train-pdf-support-goal

Etherpad to track common issues: https://etherpad.openstack.org/p/pdf-goal-train-common-problems

Storyboard: https://storyboard.openstack.org/#!/story/list?tags=pdf-doc-enabled



NOTE: Below is no longer in use

Full name (IRC nickname) Project name Tracking etherpad Test status
Akihiro Motoki (amotoki) Neutron https://etherpad.openstack.org/p/pdf-goal-train-neutron TBD
Donny Davis Nova https://etherpad.openstack.org/p/pdf-goal-train-nova TBD
Michael Johnson (johnsom) Octavia https://etherpad.openstack.org/p/pdf-goal-train-octavia TBD
Luigi Toscano (tosky) Sahara https://etherpad.openstack.org/p/pdf-goal-train-sahara TBD
Bogdan Dobrelya (bogdando) TripleO https://etherpad.openstack.org/p/pdf-goal-train-tripleo TBD

References

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