-
Notifications
You must be signed in to change notification settings - Fork 133
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?
- Build and Archive Legacy Documentation
- How to check broken links
- How to build PDF
- How to add a new file to the site
- How to build the site
- How to prepare appendix for a new release
- How to embed videos in Zowe docs
- How to write what's new/release notes
- How to report documentation progress and status?
- How to author in Markdown?
- How to author content or a new release? What process to follow?
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.
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 thedocs-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 thedocs-staging
branch. Then make and commit changes on your new branch. When changes are ready, create a PR to merge into thedocs-staging
branch and fill in the PR information to request review etc. When the review is done, the PR can be merged to thedocs-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 themaster
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 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.
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
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
.
-
Double check
master
branch is ready to be archived.- All
v1.1.x
information should be in place andv1.2.x
information are on thedocs-staging
branch and not merged intomaster
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.
- All
-
Go to the Zowe Jenkins build pipeline https://wash.zowe.org:8443/job/docs-site-archive/.
-
Scroll down to locate the
master
branch. ClickBuild with Parameters
. -
Input
v1.1.x
asRELEASE_VERSION
parameter, then click onBUILD
.The build will create a protected branch called
v1.1.x
. Same asmater
branch, any changes made to this branch requires pull request, reviewer and DCO check passed. -
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
branchv1-1-x
folder. Please note, the folder name is using-
instead of.
, which is a limitation of VuePress. -
Update the Algolia crawler configuration to enable search for the new version.
-
Go to https://github.com/algolia/docsearch-configs/blob/master/configs/zowe.json#L7.
-
Click the Edit pen to edit this file.
-
If we have new
v1.1.x
version, add an entry of"v1-1-x"
tostart_urls.0.variables.version
array. -
Create a Pull Request.
-
-
Go to the
docs-staging
branch and add a new record todocs/.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 aVersions
dropdown with options to switch tov1.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.
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.
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.
-
source: in 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.
-
source: in page
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.
To add content to the site:
- Navigate to the docs folder, and then place your Markdown file in the appropriate folder (ie: docs/user-guide).
- Navigate to the config.js file at: /docs/.vuepress/config.js.
- 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']
}
- Commit your changes.
If you simply want to edit pages that are already there:
- Edit markdown file (ie: docs/user-guide/aboutthisbook.md).
- Commit changes with git.
npm install
(first time)
npm run docs:dev
-
npm install
(first time) - Run
npm run docs:dev
. (or use yarn for slightly faster process. google it and install first, then use justyarn docs:dev
(You can kill process using ctrl+z or close window) - Navigate to port on 'Done' message.
- For example
http://localhost:8080/docs-site/
- For example
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
.
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.
-
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.
-
Create a new branch based on the previous release branch. For example, select
v1.5.0/master
and create a new branch namedv1.6.0/master
. -
In your new branch, open the file named
Jenkinsfile.license-scan
. -
Edit the line of code
ZOWE_MANIFEST_BRANCH:
to add the new value ofv1.6.0
.Tip: If you need to build this for an RC prior to release, you can type
rc
instead. -
Save, commit, and push your change.
-
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.
-
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. -
Then extract the
license_reports.zip
file and locate themarkdown_dependency_report.md
file. -
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 thetpsr.md
file. -
Open a Pull Request when ready.
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.
- Stop (
CMD + Z
) and rerun start scriptnpm run docs:dev
- 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.
- 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/latest (bump by 2 if you rebuild in same cmd window/process)- Live Site - https://zowe.github.io/docs-site/latest
- Yarn install - https://yarnpkg.com/en/docs/install#windows-stable
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>
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.
Update your status periodically on issues in GitHub and Waffle.io. https://waffle.io/zowe/docs-site
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.
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/
-
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/
-
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/
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.
The following process is recommended:
-
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.
-
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
. -
Create a draft of the documentation in Markdown and place the file in the target directory.
-
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.
-
If you installed spelling checker or tool like Acrolinx, run it to fix typos and grammar issues.
-
If you added a new file, update the navigation file here: /docs/.vuepress/config.js.
-
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
```
.
-
Run the broken link checker locally and fix broken links if any.
-
Commit the changes.
-
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...)
- Merge the PR.
- Doc readiness checklist
- Doc planning
- Doc maintainers
- What is the Pull Request process and how to submit a PR?
- Build and Archive Legacy Documentation
- How to check broken links
- How to build PDF
- How to add a new file to the site
- How to build the site
- How to prepare appendix for a new release
- How to embed videos in Zowe docs
- How to write what's new/release notes
- How to report documentation progress and status?
- How to author in Markdown?
- How to author content or a new release? What process to follow?