Skip to content

How to

Jump to bottom
nannanli edited this page Feb 5, 2021 · 15 revisions

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

Build and Archive Legacy Documentation

Automatic Build

Build will be automatically triggered by commit or pull request, and pipeline Jenkinsfile will be executed. Build result will be published to gh-pages branch latest folder, which will be synced to Github Pages hosting.

Tag A Patch Version

At the release date of Zowe, we should tag the version. For example, we are releasing Zowe v0.10.3 today, we need to create and push tag like this:

git checkout master
git pull
git tag v0.10.3
git push --tags

Archive Document And Create A Version

Q: First, when should we archive a doc version?

A: We should archive last version of documentation before a new Zowe minor release is ready, or new Zowe minor version features are about to be merged into master branch. For example, latest Zowe stable version is v1.1.0, and we are preparing for v1.2.0. Before v1.2.0 feature documentation is merged to master, we should archive the v1.1.x documentation, to make sure v1.2.x features are not in v1.1.x documentation.

Please follow these steps to archive documentation. Below example are based on archiving v1.1.x before we start v1.2.x.

  1. Double check master branch is ready to be archived.

    • All v1.1.x information should be in place and v1.2.x information are on the docs-staging branch and not merged into master yet.
    • Merge the open PRs that go to the master branch if possible. Otherwise, remember to backport the changes to the archived version after the PR is ready to be merged.

  2. Go to the Zowe Jenkins build pipeline https://wash.zowe.org:8443/job/docs-site-archive/.

  3. Scroll down to locate the master branch. Click Build with Parameters.

  4. Input v1.1.x as RELEASE_VERSION parameter, then click on BUILD.

    The build will create a protected branch called v1.1.x. Same as mater branch, any changes made to this branch requires pull request, reviewer and DCO check passed.

  5. Build the new branch. Go to https://wash.zowe.org:8443/blue/organizations/jenkins/docs-site/branches/, scroll to locate the new branch you created, and click on Build.

    This will publish the build result to gh-pages branch v1-1-x folder. Please note, the folder name is using - instead of ., which is a limitation of VuePress.

  6. Update the Algolia crawler configuration to enable search for the new version.

    1. Go to https://github.com/algolia/docsearch-configs/blob/master/configs/zowe.json#L7.

    2. Click the Edit pen to edit this file.

    3. If we have new v1.1.x version, add an entry of "v1-1-x" to start_urls.0.variables.version array.

    4. Create a Pull Request.

  7. Go to the docs-staging branch and add a new record to docs/.vuepress/versions.json. Please make sure your JSON file is valid. Example record:

    Then, create a pull request to merge the new version entry change into master branch. After build, the latest version of documentation website will have a Versions dropdown with options to switch to v1.1.x documentation.

Now we have two documentation threads:

  • master: this is the main thread, same as before. Changes added to this branch will be automatically published to /latest path.
  • v1.1.x: this is the legacy version v1.1.x thread. Any changes added to this branch will be automatically published to /v1-1-x path.

As time goes, we may have multiple legacy versions. We can still go back to version branch to make changes, fix errors.

How to check broken links

You will need Docker to run broken links test. Check https://www.docker.com/get-started to install Docker.

You can test broken links with these commands. First compile the documentation with command:

npm run docs:build

Then run broken links test with this command:

npm run test:links:latest

Check Warning of broken links and other issues (source target lines code fragments): sections for warnings, and Check Errors of broken links and other issues (source target lines code fragments): sections for errors.

Errors must be fixed before merge to master branch, otherwise the pull request will be blocked.

Please note, if we have multiple documentation versions in place, you may see broken links warnings on links to other versions.

Understand The Link Check Warning / Error Message

If you don't see a section of Error(s) of broken links and other issues in the job console log, that means you are all good to go! However, there may be a Warning(s) of broken links and other issues which includes warnings but it won't fail the build pipeline. The (source target lines code fragments) indicates the fields of each warning / error message.

A typical link check warning message may looks like this:

=================================================================================
Warning(s) of broken links and other issues (source target lines code fragments):
- http://zowe-docs-test-links/docs-site/v0-9-x/user-guide/mvd-using.html http://zowe-docs-test-links/docs-site/v0-9-x/user-guide/mvd-using.html "16, 20, 24, 25" "200 OK" "#api-mediation-layer-architecture"
- http://zowe-docs-test-links/docs-site/v0-9-x/getting-started/summaryofchanges.html http://zowe-docs-test-links/docs-site/v0-9-x/user-guide/cli-usingcli.html "24" "200 OK" "#accessing-an-api-mediation-layer"
- http://zowe-docs-test-links/docs-site/v0-9-x/user-guide/systemrequirements.html http://zowe-docs-test-links/docs-site/v0-9-x/user-guide/systemrequirements.html "24" "200 OK" "#zosmf-configuration"
- http://zowe-docs-test-links/docs-site/v0-9-x/user-guide/cli-installcli.html http://zowe-docs-test-links/docs-site/v0-9-x/user-guide/cli-installcli.html "24, 33" "200 OK" "#testing-zowe-cli-connection-to-zosmf"
- http://zowe-docs-test-links/docs-site/v0-9-x/user-guide/cli-installcli.html http://zowe-docs-test-links/docs-site/v0-9-x/user-guide/cli-usingcli.html "26, 29, 34" "200 OK" "#displaying-zowe-cli-help,#accessing-an-api-mediation-layer"
- http://zowe-docs-test-links/docs-site/v0-9-x/getting-started/overview.html http://zowe-docs-test-links/docs-site/v0-9-x/user-guide/mvd-using.html "16, 20, 24" "200 OK" "#using-zowe-framework-application-plug-ins"
- http://zowe-docs-test-links/docs-site/v0-9-x/user-guide/cli-usingcli.html http://zowe-docs-test-links/docs-site/v0-9-x/user-guide/cli-installcli.html "29, 46, 74" "200 OK" "#testing-zowe-cli-connection-to-zosmf,#Creating-a-profile-to-access-an-API-Mediation-Layer"
- http://zowe-docs-test-links/docs-site/v0-9-x/user-guide/cli-usingcli.html http://zowe-docs-test-links/docs-site/v0-9-x/user-guide/cli-usingcli.html "24, 28, 47" "200 OK" "#displaying-zowe-cli-help,#Understanding-command-option-order-of-precedence"
- http://zowe-docs-test-links/docs-site/v0-9-x/extend/extend-apiml/api-mediation-onboard-an-existing-java-rest-api-service-without-spring-boot-with-zowe-api-mediation-layer.html http://zowe-docs-test-links/docs-site/v0-9-x/extend/extend-apiml/api-mediation-onboard-an-existing-java-rest-api-service-without-spring-boot-with-zowe-api-mediation-layer.html "24" "200 OK" "#add-context-listener"
- http://zowe-docs-test-links/docs-site/v0-9-x/extend/extend-desktop/zlux-app-server.html http://zowe-docs-test-links/docs-site/v0-9-x/extend/extend-desktop/zlux-app-server.html "24" "200 OK" "#7-connect-in-a-browser,#3-set-the-server-configuration,#5-deploy-server-configuration-files,#1-acquire-the-source-code,#2-acquire-external-components,#0-optional-install-git-for-zos,#6-run-the-server,#4-build-application-plug-ins"
- http://zowe-docs-test-links/docs-site/v0-9-x/extend/extend-cli/cli-devTutorials.html http://zowe-docs-test-links/docs-site/v0-9-x/extend/extend-cli/cli-devTutorials.html "16, 20, 24" "200 OK" "#why-create-a-zowe-cli-plug-in"
- http://zowe-docs-test-links/docs-site/v0-9-x/extend/extend-cli/cli-implement-profiles.html http://zowe-docs-test-links/docs-site/v0-9-x/extend/extend-cli/cli-devTutorials.html "16, 20, 24, 88" "200 OK" "#Imperative-CLI-Framework-documentation"
- http://zowe-docs-test-links/docs-site/v0-9-x/extend/extend-apiml/api-mediation-security.html http://zowe-docs-test-links/docs-site/v0-9-x/extend/extend-apiml/api-mediation-security.html "24" "200 OK" "#add-a-service-with-an-existing-certificate-to-apiml-on-zos,#generating-keystore-and-truststore-for-a-new-service-on-zos,#certificates-for-zos-installation-from-the-zowe-pax-file,#zowe-runtime-on-zos,#authentication-1,#trust-zosmf-certificate"
- http://zowe-docs-test-links/docs-site/v0-9-x/extend/extend-apiml/api-mediation-onboard-an-existing-java-jersey-rest-api-service.html http://zowe-docs-test-links/docs-site/v0-9-x/extend/extend-apiml/api-mediation-onboard-an-existing-java-jersey-rest-api-service.html "24" "200 OK" "#validate-discovery-of-the-api-service-by-the-discovery-service"
- http://zowe-docs-test-links/docs-site/v0-9-x/user-guide/install-zos.html http://zowe-docs-test-links/docs-site/v0-9-x/extend/extend-apiml/api-mediation-security.html "86" "200 OK" "#trust-zosmf-certificate"
- http://zowe-docs-test-links/docs-site/v0-9-x/user-guide/install-zos.html http://zowe-docs-test-links/docs-site/v0-9-x/user-guide/install-zos.html "24, 74" "200 OK" "#starting-and-stopping-the-zowe-runtime-on-zos,#how-the-install-script-zowe-installsh-works,#installing-the-zowe-runtime-on-zos"
- http://zowe-docs-test-links/docs-site/v0-9-x/user-guide/installroadmap.html http://zowe-docs-test-links/docs-site/v0-9-x/user-guide/cli-installcli.html "24" "200 OK" "#testing-zowe-cli-connection-to-zosmf"
- http://zowe-docs-test-links/docs-site/v0-9-x/extend/extend-desktop/zlux-workshop-user-browser.html http://zowe-docs-test-links/docs-site/v0-9-x/extend/extend-desktop/zlux-workshop-user-browser.html "24, 300, 409" "200 OK" "#defining-your-first-plugin,#constructing-an-app-skeleton,#adding-your-dataservice-to-the-app,#adding-your-app-to-the-desktop,#calling-back-to-the-starter-app,#packaging-your-web-app"
- http://zowe-docs-test-links/docs-site/v0-9-x/extend/extend-desktop/mvd-apptoappcommunication.html http://zowe-docs-test-links/docs-site/v0-9-x/extend/extend-desktop/mvd-apptoappcommunication.html "24" "200 OK" "#why-application-to-application-communication"
- http://zowe-docs-test-links/docs-site/v0-9-x/user-guide/cli-cicsplugin.html http://zowe-docs-test-links/docs-site/v0-9-x/user-guide/cli-cicsplugin.html "24, 31" "200 OK" "#setting-up-profiles,#get-cics-resources"
- http://zowe-docs-test-links/docs-site/v0-9-x/user-guide/cli-db2plugin.html http://zowe-docs-test-links/docs-site/v0-9-x/user-guide/cli-db2plugin.html "24, 46" "200 OK" "#executing-an-sql-statememnt,#setting-up-profiles,#license"
- http://zowe-docs-test-links/docs-site/latest/user-guide/cli-cicsplugin.html http://zowe-docs-test-links/docs-site/latest/user-guide/cli-installcli.html "24, 27" "200 OK" "#installing-zowe-cli-from-local-package"
- http://zowe-docs-test-links/docs-site/latest/user-guide/cli-usingcli.html http://zowe-docs-test-links/docs-site/latest/user-guide/cli-installcli.html "29, 50" "200 OK" "#creating-a-zowe-cli-profile,#testing-zowe-cli-connection-to-zosmf"
- http://zowe-docs-test-links/docs-site/latest/extend/extend-apiml/api-mediation-onboard-an-existing-java-rest-api-service-without-spring-boot-with-zowe-api-mediation-layer.html http://zowe-docs-test-links/docs-site/latest/extend/extend-apiml/api-mediation-onboard-an-existing-java-rest-api-service-without-spring-boot-with-zowe-api-mediation-layer.html "24" "200 OK" "#add-context-listener"
- http://zowe-docs-test-links/docs-site/latest/extend/extend-apiml/api-mediation-security.html http://zowe-docs-test-links/docs-site/latest/extend/extend-apiml/api-mediation-security.html "24" "200 OK" "#add-a-service-with-an-existing-certificate-to-api-ml-on-zos,#zowe-runtime-on-zos,#certificates-for-zos-installation-from-the-zowe-pax-file,#trust-a-zosmf-certificate,#generate-a-keystore-and-truststore-for-a-new-service-on-zos"
- http://zowe-docs-test-links/docs-site/latest/user-guide/systemrequirements.html http://zowe-docs-test-links/docs-site/latest/user-guide/systemrequirements.html "24" "200 OK" "#zosmf-configuration"
- http://zowe-docs-test-links/docs-site/latest/user-guide/install-zos.html http://zowe-docs-test-links/docs-site/latest/user-guide/install-zos.html "24, 75, 110, 175" "200 OK" "#installing-the-zowe-cross-memory-server-on-zos,#verifying-z-os-services-installationn,#installing-the-zowe-runtime-on-zos,#starting-and-stopping-the-zowe-cross-memory-server-on-zos,#how-the-install-script-zowe-installsh-works,#starting-and-stopping-the-zowe-runtime-on-zos"
- http://zowe-docs-test-links/docs-site/latest/user-guide/install-zos.html http://zowe-docs-test-links/docs-site/latest/extend/extend-apiml/api-mediation-security.html "88" "200 OK" "#trust-zosmf-certificate"
- http://zowe-docs-test-links/docs-site/latest/extend/extend-desktop/zlux-app-server.html http://zowe-docs-test-links/docs-site/latest/extend/extend-desktop/zlux-app-server.html "24, 46" "200 OK" "#2-acquire-external-components,#0-optional-install-git-for-zos,#6-run-the-server,#4-build-application-plug-ins,#5-deploy-server-configuration-files,#1-acquire-the-source-code,#7-connect-in-a-browser,#3-set-the-server-configuration"
Total 29 warning(s).

A typical link check error message may looks like this:

===============================================================================
Error(s) of broken links and other issues (source target lines code fragments):
- http://zowe-docs-test-links/docs-site/latest/ https://zowe.github.io/docs-site/latest/Zowe_Documentation_1.0.0.pdf "26" "404 Not Found" "-"
- http://zowe-docs-test-links/docs-site/latest/ http://zowe-docs-test-links/docs-site/latest/... "26" "404 Not Found" "-"
Total 2 error(s).

The above warning / error message includes several informations:

  • There are 29 warnings found in the docs build result.
  • There are 2 errors found in the docs build result.
  • Each line starts with - is one particular warning / error.
  • Each warning / error line includes 5 fields:
    • source
    • target
    • lines, separated by comma (,)
    • code
    • fragments, separated by comma (,)
  • For line - http://zowe-docs-test-links/docs-site/v0-9-x/user-guide/cli-installcli.html http://zowe-docs-test-links/docs-site/v0-9-x/user-guide/cli-usingcli.html "26, 29, 34" "200 OK" "#displaying-zowe-cli-help,#accessing-an-api-mediation-layer", it means:
    • source: in page /docs-site/v0-9-x/user-guide/cli-installcli.html,
    • targe: has a link to /docs-site/v0-9-x/user-guide/cli-usingcli.html, which is itself,
    • lines: at line 26, 29, 34, which is 3 lines,
    • code: received code 200 OK, which means retreiving target link is successful,
    • fragments: however it failed to find 2 target fragments #displaying-zowe-cli-help,#accessing-an-api-mediation-layer in the target html page.
  • For line http://zowe-docs-test-links/docs-site/latest/ https://zowe.github.io/docs-site/latest/Zowe_Documentation_1.0.0.pdf "26" "404 Not Found" "-", it means:
    • source: in page /docs-site/latest/,
    • targe: has a link to https://zowe.github.io/docs-site/latest/Zowe_Documentation_1.0.0.pdf,
    • lines: at line 26,
    • code: received error code 404 Not Found,
    • fragments: without fragments defined.

How to build PDF

Launch the build script with command npm run docs:pdf. The build result will be put into .deploy/.pdf/out folder if there are no errors.

To update what should be included in PDF document, go ahead edit docs/.vuepress/config.js ALL_PAGES property.

Check Build PDF for detailed explanations.

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/

How to prepare appendix for a new release

For each Zowe minor release (1.1.0, 1.2.0, etc...), update tpsr.md and bill-of-materials.md in zowe/docs-site/appendix.

Third-Party Software Requirements (TPSRs)

Update TPSRs in the master branch immediately after a Release Candidate (RC) is approved/released. Update the active-development TPSRs periodically as well - it has some different dependencies.

  1. Navigate to the Dependency Scan repository: https://github.com/zowe/zowe-dependency-scan-pipeline

    Tip: If you do not have access to the repository or Jenkins pipeline, reach out to a CI/CD Squad or Doc Squad member.

  2. Create a new branch based on the previous release branch. For example, select v1.5.0/master and create a new branch named v1.6.0/master.

  3. In your new branch, open the file named Jenkinsfile.license-scan.

  4. Edit the line of code ZOWE_MANIFEST_BRANCH: to add the new value of v1.6.0.

    Tip: If you need to build this for an RC prior to release, you can type rc instead.

  5. Save, commit, and push your change.

  6. Navigate to the Jenkins pipeline at the following URL. To configure the build for the branch you created, click Scan Repository Now on the left-hand side of the screen: https://wash.zowe.org:8443/job/Zowe%20Dependency%20Scan%20-%20Multibranch/job/v1.5.0%252Fmaster/

    For all subsequent runs, simply click Build with Parameters.

  7. After the build is complete, there will be three .zip files for download. Select license_reports.zip and click to download it to your desktop.

  8. Then extract the license_reports.zip file and locate the markdown_dependency_report.md file.

  9. Copy the content in the markdown_dependency_report.md file. Go to the /docs folder, navigate to /appendix/tpsr.md, and replace all the content in the tpsr.md file.

  10. Open a Pull Request when ready.

Bill of Materials (BoM)

The BoM is a manifest that includes every artifact that Zowe delivers to customers (PAX file, CLI components, etc...). At this time, you must manually update the BoM for each release. Check in with your friendly CI/CD squad member to learn if there are any new artifacts.

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