Documentation team FAQ for Rackspace Public Cloud and Managed services#

This FAQ is intended to help Rackspace Public and Managed Cloud developers and support team members contribute to the documentation.

As developers and support team members, you routinely communicate your expert product knowledge in the course of your work. When you write down that knowledge, you enable the Information Design and Development (doc) team to work with you to turn your words into expert, professional customer documentation that we can deliver to the Rackspace documentation and support sites.

In this process, the people with the expertise and product knowledge perform as much of the content production cycle as they reasonably can and, in turn, the doc team provides:

  • Guidance in using our documentation platform and tools
  • Templates and writing guidance
  • Expertise in information development and architecture
  • Reviews, editorial feedback, and publication approval

This collaborative process most often expedites the addition of smaller changes to content. The doc team still drives the overall documentation strategy and large changes to the content sets. If you want to make large changes but aren’t quite sure what to do, you can ask for help by opening an issue in the project’s GitHub repo. Alternatively, you can make and submit large changes via a PR. The doc team will review and edit the changes as necessary.

For additional information, see the following sections:

Who is the doc team and what do we do?#

Documentation is produced by the Rackspace Information Development team. This section lists the team members with their primary areas of expertise, but team members often do different work depending on business needs and priorities. Team members also contribute to OpenStack manuals.

The team consists of Information Developers (technical writers), Information Architects, and Editors.

  • Information Developers are professional writers who produce technical documentation that helps people understand and use a product or service.
  • Information Architects ensure that the structural design of shared information environments (our documentation) supports usability and findability.
  • Editors work closely with the Information Developers and Information Architects to ensure that all documentation uses a consistent tone and follows standards as described in the Rackspace style guide.

Following are the members of the team:

  • Karin Levenstein - Information Development Manager, Austin

    • Catherine Richardson - Senior Technical Editor, Austin
    • Christopher Moyer - Information Developer IV, Austin
    • Erik Wilson - Information Developer IV, Austin
    • Robb Romans - Team Lead for Doc Tools - Information Developer V, Austin
    • Matt Penna - Information Developer IV, Remote
    • Svetlana Karsliogu - Information Developer III, Remote
  • Renee Rendon (San Antonio) - Team lead (Information Developer V)

    for San Antonio Information Developers

    • Cat Lookabaugh - Information Developer IV, San Antonio
    • Kate Dougherty - Information Developer II, Remote
    • Stephanie Fillmon - Information Developer II, San Antonio

API documentation#

This section answers questions about the Rackspace API documentation.

Where do the API docs live?#

The API docs are located in the following https://github.com/rackerlabs repos:

The most important folder in these repos is /api-docs. If the product has more than one supported version, separate documentation is maintained in version-specific directories under /api-docs.

The /api-docs folder (or the version-specific subfolder) contains the following external guides that are published to the Rackspace Developer Docs site:

  • Getting Started Guide
  • Developer Guide
  • API Reference
  • Release Notes

What do the API docs contain?#

The Getting Started Guide provides the following information:

  • Prerequisites for using the product API
  • Installation instructions for cURL and clients
  • Information about sending API requests
  • Instructions for API authentication
  • Use cases for basic product operations, including the necessary commands to execute each step

The Developer Guide contains information to assist software developers who want to develop applications by using the REST API for the product, including the following information:

  • Explanation of product concepts
  • General API information, including:
    • Service access endpoints
    • Request and response types
    • Limits and quotas
    • Role based access control

The API Reference provides a list of all supported API operations, including:

  • The operation URI
  • Additional information regarding the operation and its use
  • Lists of URI, query, request body, and response body parameters
  • Examples of request and response bodies, if any

The Release Notes describes new features and known and resolved issues in the current release of the product or service.

How do we contribute to API docs?#

Rackspace Cloud services documentation uses GitHub for code, bug and issue management, and code reviews.

To learn how to contribute to API documentation, see the following instructions:

  • GitHub workflow found in GITHUBING.rst in the root directory of the product repo
  • Contributor guidelines found in CONTRIBUTING.rst in the root director of the product repo

For example, see the following documents in the Cloud Servers repo:

How-To and Control Panel articles#

This section answers questions about the How-To articles.

Where do the How-To articles live?#

The How-To article repo is at https://github.com/rackerlabs/rackspace-how-to.

The most important folder is /content. This folder contains the subdirectories, with article source files, for each of the Public Cloud products and services.

What do the How-To articles contain?#

How-To articles provide users and system administrators with tactical, troubleshooting, and FAQ information for Rackspace products and services. How-To articles also provide instructions to set up and maintain Rackspace products from the Rackspace Cloud Control Panel.

How do we contribute to How-To articles?#

The How-To uses GitHub for code, bug and issue management, and code reviews.

To learn how to contribute to How-To articles, see Contributing to the Rackspace How-To content repository.