Standardize layout of action pages.

narcher7 commented 9 years ago

Problem: Renee met with Deepak Mohan, a new Racker who had the idea to add code blocks (cURL or Rack CLI examples) to the Cloud Server's actions page (https://developer.rackspace.com/docs/user-guides/infrastructure/cloud-config/compute/cloud-servers-product-actions/). This was an idea we had earlier in the summer but dropped when we standardized common content for the API docs.

The addition of code blocks to the actions pages of each product in the Core-Infra guide actually raises a large issue with the pages themselves. Namely, the layout of each page lacks consistency. Cloud Servers, Block Storage, and Files (follow link above) lists actions followed by brief descriptions of the action, whereas Cloud Images and Networks (https://developer.rackspace.com/docs/user-guides/infrastructure/cloud-config/compute/cloud-images-product-actions/) formats actions as a bulleted list.

Which format is more fitting in this particular instance is a matter of debate. Cloud Servers and Images won't be include in the other service-based user guides, so an actions page describing Cloud Server's basic actions makes sense. A simple list of actions (like the Cloud Images page itself) might not have enough detail when compute services aren't included in any other User Guide.

However, the bulleted list of actions does fall in line with the stated purpose of the guide as a high-level entry point into our managed cloud and our more-detailed documentation. However, the list is unattractive and basically useless when users have the api-reference material and the Rack CLI user guide's 'command reference' page (https://developer.rackspace.com/docs/rack-cli/services/servers/).

Solutions: Issue #346 may be a step towards solving this issue, but not the best one, as a matrix would simply require a user to either follow a link to the reference material or find the material themselves.

Another possibility is to only give examples for the most common commands of each service, with code blocks for each. We could link out to more advanced actions while covering the ones needed for basic implementation. The layout would be similar to the Cloud Server's page, and for services included in another user guide, we could link out to the services' respective user guides and include a more detailed list of actions there.

rose-coste commented 8 years ago

A template for product-action contributions is under construction at https://github.com/rackerlabs/docs-templates/blob/master/user-guide/user-guide-fragments/action.md; @DonNateR, you're very welcome to help figure out what that should be. After we settle on a template, we can make everything match it on all the product-actions pages (inconsistent now):

narcher7 commented 8 years ago

@rose-coste I'll take a look!

rose-coste commented 8 years ago

Thanks. @dpkmohan asked for good models of small contributions to help Product Managers keep making small, well-formed improvements to existing guides; more of that is starting at https://github.com/rackerlabs/docs-templates/tree/master/user-guide/user-guide-fragments. It's all part of the long-term evil plot to use consistency to simplify both writing and reading. I won't name the other conspirators but one of them might operate under the alias @kmsholcomb.

rackerlabs / docs-core-infra-user-guide

Standardize layout of action pages. #382