Skip to content

Latest commit

 

History

History
80 lines (64 loc) · 4.15 KB

contributing_user_stories.adoc

File metadata and controls

80 lines (64 loc) · 4.15 KB
Raw

Contribute user stories to OpenShift documentation

Modularization backstory

OpenShift docs are getting modularized, starting from OpenShift 4.0. All existing content will be completely replaced with content that is based on user stories and complies with the modularization guidelines. All future content must support a user story.

How do I contribute user stories?

Familiarize yourself with the Customer Content Services (CCS) modularization guide. This is an important first step in making sure you are helping the docs team create content that is fully modularized.

What is the branch setup for modularized docs?

  • enterprise-4.0

    This builds both OCP 4.0 and OKD/Upstream content. Just like today, OKD content will be separated using ifdef statements in content and distro statements in the _topic_map.yml.

    Only CCS submits and merges their PRs here until OCP 4.0 is released unless others are keen to submit content in modularized format.

  • master This builds legacy (existing), mostly non-user story based content. This branch will continue to update docs.okd.io (upstream) until we switch to 4.0 with the enterprise-4.0 branch.

    Please continue to submit your PRs to this branch and specify if it is for 3.11 and/or 4.0. If the submitted PR is for the 3.11 branch, CCS merges with follow up edits in 3.11. CCS then creates user stories for its inclusion in enterprise-4.0 branch.

  • enterprise-3.11 This branch contains content for the 3.11 branch and the last branch that contains content that is not completely modularized.

    This may contain modularized content based on user stories for content for completely new features.

Do you have a template for submitting user stories if I don’t want to contribute content in a modularized format?

Instead of a template, we have a series of questions for you to answer to provide us with the information that we need to write the user story and start drafting the content.

The basic format of a user story is:

As a <type of user>, I want to <goal state> because <reason behind the goal>.

For example, "As a cluster administrator, I want to enable an Auto Scaling group to manage my OpenShift Enterprise cluster deployed on AWS because I want my node count to scale based on application demand."

Use the following questions to guide you in providing the context for your user story and the necessary technical details to start a draft. You don’t have to answer all of these questions, only the ones that make sense to your particular user story.

Feature info

  • What is the feature being developed? What does it do?

  • How does it work?

  • Are there any configuration files/settings/parameters being added or modified? Are any new commands being added or modified?

  • What tools or software does the docs team need to test how this feature works? Does the docs team need to update any installed software?

  • Are there any existing blogs, Wiki posts, Kbase articles, or Bzs involving this feature? Or any other existing information that may help to understand this feature?

Customer impact

  • Who is the intended audience for this feature? If it’s for Enterprise, does it apply to developers, admins, or both?

  • Why is it important for our users? Why would they want to use this feature? How does it benefit them?

  • How will the customer use it? Is there a use case?

  • How will the customer interact with this feature? Client tools? Web console? REST API?

Product info

  • Is this feature being developed for Online? Enterprise? Dedicated? OKD? All?

  • Will this feature be rolled back to previous versions?

  • If it’s for Online, what type of plan do users need to use this feature?

  • Is it user-facing, or more behind-the-scenes admin stuff?

  • What tools or software does the docs team need to test how this feature works?