Zowe doc planning (2020)

"I wish Zowe Docs would..."

Start

What do we need to start doing or bring on the agenda in 2020?

Content development and experience

Improve users' end-to-end content experience.

• Idea: Create a resources page that consolidates useful blogs, videos, articles, websites that users could go to find Zowe related information to complement the existing documentation.
• Idea: Provide an interactive on-boarding path on the doc site that recommends a learning path and learning resources based on user role and areas of interest. The goal is to provide better beginner experience and reduce on-boarding time.
• Doc quality: Run tools like Acrolinx to catch and fix quality issues (typos, grammar, etc)
• API doc

Search and discovery

Enable users to find what they need.

• The search function is very useful but a lot of customers are not aware that they could search the docs. The search button is not so outstanding or obvious. We could perhaps so something to improve this.
• Can we move the search box to zowe.org, for example. a box perhaps labeled Search docs.
• Also, on zowe.org, when people click Docs, they are not directed to the doc site immediately. Instead, they are directed to the section below and have to click Read the docs again to go to the doc site. This could be improved. The Docs section can also add more useful links like Installing z/OS components.
• Customers find the Configuring Zowe section very confusing. The information there are optional. but people tend to think that it's required. Consider changing the name of this section. Like "Advanced configuration", "Post-installation configuration", etc and make it clear that these are optional.
• People cannot discover some useful guidelines, such as the video guideline (how to contribute a video).

Automation

• Automate the generation of release notes
• Program Directory automation

Data and insights

• SEO
• Use web analytics data (Google Analytics, Google Search Console, NPS, etc) to drive actionable insights to improve docs

Process

• More visibility into changes that affect docs

Stop

What didn't go so well? What should be improved?

• DCO sign-off issue is a big pain, which took a lot of time communicating and fixing them. There should be a way to better handle this. For example, enable alert in the commit message field in both web UI, CLI, and web desktop.
• A lot of branches need to be cleaned/removed. The branch names vary and makes it difficult to determine which can be deleted and which not.

Continue

What went well in 2019 that we should carry on in 2020?

• Continue to get feedback from users and the community.