Skip to content

How to

Jump to bottom
nannanli edited this page Feb 21, 2019 · 15 revisions

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

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']   
    }
  1. 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:

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: 

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...)
  1. Merge the PR.

Release management for docs

How-tos

Best practices for docs

User feedback

Clone this wiki locally