- Contributing to Zowe Documentation
You are welcome to contribute to the Zowe™ documentation repository. Anyone can open an issue about documentation, or contribute a change with a pull request (PR) to the zowe/docs-site GitHub repository. However, before contributing a documentation change to the repository, you should be familiar with:
- Git and Github: To learn about git and GitHub, refer to the Github Guides.
- Slack: The Zowe Documentation team communicates using the Slack application. To learn about Slack, refer to the Slack Help Center. The Zowe team is part of the Open Mainframe Project channel.
- Markdown Language: The Zowe documentation is written in Markdown language. To learn about Markdown, refer to The Markdown Guide
In addition to being familiar with the Zowe community and how we work together, you will need to sign the CNCF Contributor License Agreement. The Contributor License Agreement defines the terms under which you contribute to Zowe documentation. Contributions to Zowe documentation are reviewed before being committed to the repository. Committing changes to the Zowe repository requires additional access rights. See https://github.com/zowe/community/blob/master/COMMITTERS.md. Also see Participating in Zowe Documentation for more details about roles and permissions.
If you are ready to get started contributing to the Zowe Documentation repository:
- Verify that you are familiar with the concepts in Before You Get Started.
- Familiarize yourself with the Zowe documentation repository
- Verify that you can open a pull request and review changes
- Open an issue for Zowe documentation if you find a problem
- Read the documentation style guide
The Zowe documentation is managed in a GitHub repository.
- Review the site's overall organization and structure
- Review the help files related to your planned changes or addition
You can provide suggested edit to any documentation page by using the Propose content change in GitHub link on each page. After you make the changes, you submit updates in a pull request for the Zowe content team to review and merge.
Follow these steps:
- Click Propose content change in GitHub on the page that you want to update.
- Make the changes to the file.
- Scroll to the end of the page and enter a brief description about your change.
- Optional: Enter an extended description.
- Select Propose file change.
- Select Create pull request.
You can request the documentation to be improved or clarified, report an error, or submit suggestions and ideas by opening an issue in GitHub for the Zowe content team to address. The content team tracks the issues and works to address your feedback.
Follow these steps:
- Click the GitHub link at the top of the page.
- Select Issues.
- Click New issue.
- Enter a title and description for the issue.
- Click Submit new issue.
This section gives writing style guidelines for the Zowe documentation.
Capitalize only the initial letter of the first word in the text and other words that require capitalization, such as proper nouns. Examples of proper nouns include the names of specific people, places, companies, languages, protocols, and products.
Example: Verifying that your system meets the software requirements.
- Building an API response
- Setting the active build configuration
- Query language
- Platform and application integration
Titles of books, CDs, videos, and stand-alone information units.
- Installation and User's Guide
- Quick Start Guides or discrete sets of product documentation
If the subject is a functional overview, begin a heading with words such as Introduction or Overview rather than contriving a pseudo-task-oriented heading that begins with Understanding, Using, Introducing, or Learning.
Italic when used outside of code examples,
If wrap using angle brackets
<>within code examples, italic font is not supported.
Where pax-file-name is a variable that indicates the full name of the PAX file you download. For example, zoe-0.8.1.pax.
Style: Put messages in quotation marks.
Example: "The file does not exist."
Example: Use the
Categories: check boxes, containers, fields, folders, icons, items inside list boxes, labels (such as Note:), links, list boxes, menu choices, menu names, multicolumn lists, property sheets, push buttons, radio buttons, spin buttons, and Tabs
Example: From the Language menu, click the language that you want to use. The default selection is English.
Example: Move the
install.exe file into the
- Run the
- Extract all the data from the
Example: In the Search field, enter
Categories: Chapter titles and section titles, entries within a blog, references to industry standards, and topic titles in IBM Knowledge Center
Style: Double quotation marks
- See the "Measuring the true performance of a cloud" entry in the Thoughts on Cloud blog.
- See "XML Encryption Syntax and Processing" on the W3C website.
- For installation information, see "Installing the product" in IBM Knowledge Center.
✔️ The API returns a promise.
❌ The API will return a promise.
✔️ The limit was exceeded.
❌ The limit has been exceeded.
✔️ In the Limits window, specify the minimum and maximum values.
❌ The Limits window is used to specify the minimum and maximum values.
Exceptions: Passive voice is acceptable when any of these conditions are true:
The system performs the action.
It is more appropriate to focus on the receiver of the action.
You want to avoid blaming the user for an error, such as in an error message.
The information is clearer in passive voice.
✔️ The file was deleted.
❌ You deleted the file.
In most cases, use second person ("you") to speak directly to the reader.
Use a preposition at the end of a sentence to avoid an awkward or stilted construction.
✔️ Click the item that you want to search for.
❌ Click the item for which you want to search.
In technical information, avoid terms of politeness such as "please" and "thank you". "Please" is allowed in UI only when the user is being inconvenienced.
Example: Indexing might take a few minutes. Please wait.
Focus technical information on users and their actions, not on a product and its actions.
✔️ User focus: On the Replicator page, you can synchronize your local database with replica databases.
❌ Product focus: The Replicator page lets you synchronize your local database with replica databases.
For whatever list or steps we are introducing, the word "following" should precede a noun.
- Before a procedure, use "Follow these steps:"
- The <component_name> supports the following use cases:
- Before you install Zowe, review the following prerequisite installation tasks:
Avoid ending the sentence with "following".
❌ Complete the following.
✔️ Complete the following tasks.
When talking about a specific version, capitalize the first letter of Version.
✔️ Java Version 8.1 or Java V8.1
❌ Java version 8.1, Java 8.1, or Java v8.1
When just talking about version, use "version" in lower case.
Example: Use the latest version of Java.
Use "can" to indicate ability, or use "might" to indicate possibility.
✔️ You can use the command line interface to update your application."
❌ "You may use the command line interface to update your application."
✔️ "You might need more advanced features when you are integrating with another application. "
❌ "You may need more advanced features when you are integrating with another application."
Example: At a command prompt, type the following command:
Use graphics sparingly.
Use graphics only when text cannot adequately convey information or when the graphic enhances the meaning of the text.
When the graphic contains translatable text, ensure you include the source file for the graphic to the doc repository for future translation considerations.
❌ The tutorials are available as PDFs. [portable document formats]
✔️ The tutorials are available as PDF files.
❌ You can FTP the files to the server.
✔️ You can use the FTP command to send the files to the server.
Use their English equivalents instead. Latin abbreviations are sometimes misunderstood.
|etc.||and so on. |
When you list a clear sequence of elements such as "1, 2, 3, and so on" and "Monday, Tuesday, Wednesday, and so on." Otherwise, rewrite the sentence to replace "etc." with something more descriptive such as "and other output."
Example: Mainframe Virtual Desktop (MVD)
Add "More information" to link to useful resources or related topics at the end of topics where necessary.
The following table alphabetically lists the common used words and their usage guidelines.
|API Mediation Layer|
|Capitalize "Server" when it's part of the product name|
|IBM z/OS Management Facility (z/OSMF) |
|zosmf (unless used in syntax)|
|personal computer |
Do not use to describe versions of software or fix packs.
|UNIX System Services |
z/OS UNIX System Services