How to

Review this section to find the how-to information about Zowe docs.

What is the Pull Request process and how to submit a PR?

Understanding the doc branches

Before you get started with the authoring work, it's necessary that you understand the different branches to work on.

• master is a branch for the published doc here: https://zowe.github.io/docs-site/latest/. This branch contains the latest release content.
• docs-staging is a branch for all of our collective work leading up to each release. We open a PR when content is ready for review, gather feedback, and merge it all at once into master branch to publish.
• v0.9.x is a branch for the published doc of version 0.9.x.
• Branches that start with release- contain archived patch release documentation for historical tracking.
• You can have your own personal branch to work on content for a certain issue or feature. However, be sure to cehck and remove unused personal branches periodically for easy maintainance. Usually when your branch is merged, you can safey delete it.

When to open a PR and how?

PR is optional when you submit changes to docs-staging branch while required for the master branch. To be specific:

For docs-staging

• You can directly submit changes to the docs-staging branch when the change does not require anyone to review such as a typo/broken link fix or simple doc changes.

  To directly submit changes, switch to the docs-staging branch on your local desktop, make the changes, and then commit and push the changes to the remote server. Then you're done! The changes will be reflected in the docs-staging branch immediately.

• It is highly recommended that you open a PR against the docs-staging branch when you have a lot of changes to make or when your work requires anyone to review before it's ready to go.

  To do this, you must create a new branch like at-tls-doc based on the docs-staging branch. Then make and commit changes on your new branch. When changes are ready, create a PR to merge into the docs-staging branch and fill in the PR information to request review etc. When the review is done, the PR can be merged to the docs-staging branch.

So as you see, a PR adds kind of a review layer to the whole process.

For master When making changes to the master branch, you have to create a PR each time. The master branch contains the official published doc and it enforces a series of checks like broken link, DCO, and build check by forcing a PR to be opened. You submit PRs against the master branch normally in two cases:

• Publish the next release doc like 1.0.1 doc. To do this, create a PR to merge the docs-staging branch into the master branch usually three days before the GA date.
• Submit doc fixes to published doc. For example, someone reported a typo, a broken link or proposed rewording of a sentence, we create a new branch based on the master branch to do the fix and open a PR.

A few considerations when you open a PR:

• Be sure the PR is going to and from the correct branches. Like to merge docs-staging to master, you'll see "master < docs-staging", read from right-to-left.
• Give a solid title and description about the updates.
• Tag reviewers, including writers and engineers
• Assign anyone who you don't expect to review but might be interested in automatic updates via email
• Add labels. In this case all component labels apply, as well as the docs label.
• Add a milestone

How to add a new file to the site

To add content to the site:

1. Navigate to the docs folder, and then place your Markdown file in the appropriate folder (ie: docs/user-guide).
2. Navigate to the config.js file at: /docs/.vuepress/config.js.
3. Scroll down to the sidebar section, and add the name of your markdown file under the appropriate section in children: [ ].     

• For example if we wanted to add a second edition notice we could write:

    {
      title: 'Edition Notice',   
      collapsable: true,   
      children: ['editionnotice, second-edition-notice']   
    }

4. Commit your changes.  

If you simply want to edit pages that are already there:

1. Edit markdown file (ie: docs/user-guide/aboutthisbook.md).
2. Commit changes with git.

How to build the site

npm install (first time) npm run docs:dev

Preview Locally

1. npm install (first time)
2. Run npm run docs:dev. (or use yarn for slightly faster process. google it and install first, then use just yarn docs:dev (You can kill process using ctrl+z or close window)
3. Navigate to port on 'Done' message.
   • For example http://localhost:8080/docs-site/

Troubleshooting

Errors when building locally?

1. Stop (CMD + Z) and rerun start script npm run docs:dev
2. If still errors, look for '<' in problem file not wrapped in code syntax.
   • Issues with files can be found at the top of red error text.
3. Look for images that are being called but do not exist in the file system.

Useful Links:

• GitHub Source - https://github.com/zowe/docs-site
• Local Build Test - http://localhost:8080/docs-site/ (bump by 2 if you rebuild in same cmd window/process)- Live Site - https://zowe.github.io/docs-site/
• Yarn install - https://yarnpkg.com/en/docs/install#windows-stable

How to embed videos in Zowe docs

Example:  https://zowe.github.io/docs-site/latest/getting-started/overview.html

Use the following code in the Markdown file and change the the title and src link to the URL of the target video: 

<iframe class="embed-responsive-item" id="youtubeplayer" title="Zowe overview demo" type="text/html" width="640" height="390" src="https://www.youtube.com/embed/NX20ZMRoTtk" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen> </iframe>

How to write what's new/release notes

It’s important to let users know about new features and functionality in each release or refresh. This section provides some guidelines for writing coherent what's new information for Zowe users. 

• Locate the What’s new topic at the top level of the TOC, at the same level as Overview.
• Highlight the latest updates first. What's new entries are presented in reverse chronological order.
• Use sections to group entries by month or by release version. Within sections, list the new features that went out.
• Writing style: Give all what's new entries catchy titles and brief descriptions. Describe why the feature matters for customers. 
• Optional: Include a Learn more link at the end of the description if applicable. Link to the specific topic.

How to report documentation progress and status?

Update your status periodically on issues in GitHub and Waffle.io.  https://waffle.io/zowe/docs-site

How to author in Markdown?

Strategically, Zowe content team decides to use Markdown as the authoring tool. Like other projects that chose Markdown as well, using Markdown opens our docs for easier collaboration with SMEs, development, users, and contributors.

What is Markdown? 

Markdown is a lightweight markup language with plain text formatting syntax designed so that it can be converted to HTML. For how to author in Markdown, you can read: 

• https://help.github.com/articles/markdown-basics/ 
• https://help.github.com/articles/github-flavored-markdown/
• https://help.github.com/categories/writing-on-github/

How do I work the source files?

1. Install GitHub Desktop

   Zowe hosts all Markdown source files in GitHub. To download all source files from the remote GitHub repository into your local desktop, you can install GitHub Desktop. For how to, see https://help.github.com/desktop/guides/getting-started-with-github-desktop/

2. Clone the doc repository and make doc changes

   After you install GitHub Desktop, you can clone the repositories, make changes locally and submit changes. For how to, see https://help.github.com/desktop/guides/contributing-to-projects/. 

Tip: Before you make a change, remember to fetch and pull the origin to get the latest content from the master repo to keep your local copy of the project in sync with the remote repository. For how to, see https://help.github.com/desktop/guides/contributing-to-projects/syncing-your-branch/

You might encounter conflicts if another person changes the same line in the same file, for how to resolve conflicts, see https://help.github.com/articles/resolving-a-merge-conflict-on-github/.

Resources: 

Resources to learn Git: https://try.github.io/

Which Markdown editor to use? 

There is no requirement on which tool you must use to edit the source files. Visual Studio Code and Atom are recommended.

Atom https://atom.io
Open source editor with tons of powerful plugins for handling things like merge conflicts: https://atom.io/packages/merge-conflicts.
This is a great editor for large teams working on the same files at the same time.

Visual Studio Code https://code.visualstudio.com/
Visual Studio Code is a powerful editor that has many useful plugins, including a plugin for running acrolinx right in your editor.
For more info on configuring its many valuable plugins, see: https://github.ibm.com/Watson/developer-experience/wiki/Visual-Studio-Code-settings

Github Web editor
Technically, Github is not an editor, it is a file repository. However, it does provide a nice Web UI for editing files you store there. This is some writer's go-to editor for quick changes. For topics you own, you can edit right to the master branch. For topics you want to suggest changes to, you can edit, create a new branch, do a Pull Request, and assign to an owner.  

How to author content or a new release? What process to follow?

The following process is recommended:

1. Collect doc input. Channels might include but are not limited to: 

   • DEV opens a pull request in GitHub or directly commit to GitHub. Writers must review the changes and ensure they are correct.
   • DEV/users/contributors post information via Zowe Slack channel. Writers open a corresponding issue in the Zowe docs-site Waffle Board and then incorporate the changes into doc. 
   • DEV provides input as comment in GitHub. Writers interact with DEV and make the corresponding changes.
   • Meet with your developers to collect doc requriements.

2. Create a new branch for this new feature work and switch to it to start working on the files. For example, create a branch named webui-new-app.

3. Create a draft of the documentation in Markdown and place the file in the target directory.

4. Ensure that you follow the Zowe writing style https://zowe.github.io/docs-site/latest/contributing.html. Key points:

   • Use sentence style capitalization for titles, like "Confirming that Node.js is installed"
   • Use gerunds to for titles of task topics, like "Installing Zowe"
   • Code technical elements consistently. 

5. If you installed spelling checker or tool like Acrolinx, run it to fix typos and grammar issues.

6. If you added a new file, update the navigation file here: /docs/.vuepress/config.js.

7. Run the build locally and verify and fix formatting by:

   • Verifying that numbered lists are displayed properly - fix if needed
   • For nested numbered lists, code them with 3 spaces indentation for the 2nd numbered list. 
   • For a list, add an extra blank line between the lead in sentence and the list to avoid that they they crash into one line in PDF.
   • Verify that titles are displayed properly (# , ##, etc)
   • Verify that codeblocks are highlighted in black when viewed in HTML. Wrap the code blocks with ```.

8. Run the broken link checker locally and fix broken links if any.

9. Commit the changes.

10. When all work is done, open a Pull Request to merge the changes to the docs-staging branch. Assign a reviewer to review this PR.

• DCO signoff must be completed on commits/PRs
• Jenkins pipeline issues must be resolved (broken links, missing files in config.js, etc...)

11. Merge the PR.