Overall doc organization

BrandonJenkins14 commented 6 years ago

We currently have 3 major sections - User Guide, Developer Tutorials, and Samples.

A few issues and ideas to start a conversation:

Some content currently in user guide is meant for Zowe developers (those who want to develop plugins/apps for Zlux, for example). This content is in the Extending zLux section. It ilooks like SDK doc - doc that describes how to use the features of a framework to develop plugins. I think we should keep the User Guide focused on usage, not development. However, INSTALLING plug-ins applies to users, and that's what should be documented in the Extending sections.
Related to the above bullet - we have Imperative CLI Framework doc for developers in the /imperative GitHub Wiki. It is not a tutorial, but could belong in a Developer Guide along with the Zlux developer material.
We have content in dev tutorials for onboarding an api to mediation layer. This is content meant for developers, but it isn't an optional tutorial - it is really the core documentation for how to accomplish something. Does this make sense to have here? I've also heard suggestions that perhaps there needs to be a separate Admin Guide to describe this type of content. Need to discuss with Andrew J.

In conclusion, perhaps we need a SDK/developer focused area to add the zLux framework and Imperative (the cli framework) doc. We should consider use cases/personas to understand what major sections we should have on the site (Admin Guide?). We should keep the user guide focused on install/config/usage. If we have an admin guide, some of that install/config info would fit there instead.

Open to ideas/discussion.

jhenryRocket commented 6 years ago

User, Admin, Developer (documentation section and a tutorials section ) sound good to me. We have some topics (Server Configuration, User Settings and Defaults, Logging) that might be included in an admin guide.

BrandonJenkins14 commented 6 years ago

I agree with that layout in general. A lot of our install doc would really belong in admin guide in a way - the z/OSMF configuration and installing zowe runtime are not done by the end user. We should clearly define what belongs in an Admin guide vs User guide vs Dev guide, then filter our topics into those categories accordingly. From there, we can build new TOCs. Let's see if others have input on this, as I am a bit unsure of myself as to what the best organization would be. We should run any proposals past dev too. We can discuss further in our next team meeting.

nannanli commented 6 years ago

I concur with these points. We can invite our SMEs (Joe, Sean, Mark perhaps) to help go through the docs site materials and provide some input for us.

Also I found something quite interesting that Kubernets is doing for their documentation: https://kubernetes.io/docs/home/?path=users&persona=app-developer&level=foundational. They provide a way to classify documentation by personas and proficiency level. Something that we can consider for our docs too.

nannanli commented 6 years ago

A good point from Joe:

One thing that came up is that in the base Zowe we let users download and install, we include the base function JES, USS and MVS Explorer, but we don’t doc any of them in terms of their function. This would be like a “user’s guide”, rather than an install doc that we have now I’m thinking this is a gap we should look at filling to help our end users.

When we have the user's guide split, we should consider expanding the current information there about how to use the base functions.

jhenryRocket commented 6 years ago

Thanks for the link to the Kubernets site Ashley! I like how they classify the documentation.

JamesBauman commented 6 years ago

Conversation in Slack about this subject: https://project-zowe.slack.com/archives/C983BA2MD/p1534836217000100

BrandonJenkins14 commented 6 years ago

I think that this post from Robert is insightful - https://openmainframeproject.slack.com/archives/CC60ALD61/p1535118698000100

"Personas to consider

Sysprogs using Zowe for their regular work
General developers using Zowe for their regular work
Specific subsystem developers using Zowe for their regular work
Subsystem administrators using Zowe for their regular work
CI/CD people using Zowe for their regular work
All of the above, but who want to customize/extend Zowe internally
All of the above but who want to customize/extends Zowe publicly (contribute specific plugins to cli or zlux)
People who install/administer their company's Zowe infrastructure
People who want to participate in the Zowe community to influence/keep-abreast-of Zowe direction
People who want to contribute to the core of Zowe
ISV's who want to develop/sell Zowe-compatible products

As per Joe's point: Right now "developer tutorials" is for 4 and 5, and people in categories 2 and 3 don't necessarily recognise that they are "users" not "developers"."

BrandonJenkins14 commented 6 years ago

From the Zowe CLI perspective, there are 3 main personas:

The systems admins/security admin who performs back-end maintenance, installation, and setup for z/OSMF and other component APIs that run on the mainframe to support the CLI (such as CICS APIs to support the Zowe CLI Plug-in for CICS).

Relevant topics: System requirements, z/OS requirements, Configuring z/OSMF

The end user, who is usually a developer or a CI/CD pipeline orchestrator, who uses the CLI in daily work to develop mainframe-based applications or write automation.

Relevant topics: Installing Zowe CLI, Configuring Zowe CLI, Extending Zowe CLI (how to install a plugin)

The developer who wants to develop for Zowe CLI in the form of a CLI plug-in or contribute to the existing code, add commands, etc....

Relevant topics: Coming Soon - Develop for Zowe CLI (this page will eventually have tutorials for how to develop a CLI plugin or add new commands to the core CLI)

General Note: Some topics could apply to multiple personas, for example Zowe Overview or Installation roadmap,

adambattenburg commented 6 years ago

@BrandonJenkins14 I agree with the three general personas you've outlined, and I think it's a sums up what we've been discussing.

The one thing I have a question about would be if a lot of the guides under "end user" are actually for "developer". That's something we can figure out later though.

BrandonJenkins14 commented 6 years ago

@adam - do you mean why did I list "Extending Zowe CLI" under the end-user persona in my notes? That's because the end-user is the person who installs plug-ins to the CLI on his/her own PC directly. While zLux plug-ins are installed on the back-end by an admin-type person. On that note, I think that the content under Extending zLUX currently is developer-focused (how to build plugins) - https://zowe.github.io/docs-site/user-guide/mvd-creatingzluxappplugins.html . But how to install plug-ins for zLUX might belong under an admin guide.

Just thinking out loud.

adambattenburg commented 6 years ago

@BrandonJenkins14 Sorry Brandon didn't notice they were all CLI based. I just saw most of the sections there and thought you were organizing the tutorials not the userguide. I still think of the userguide as a unit, but that would need to broken up as well I guess.

As far as the tutorials, I think all of them are currently developer role only. We'll need to add some others to satisfy the other roles.

nannanli commented 6 years ago

A proposal as a starting point is under discussion here https://ibm.box.com/s/p2nunfe8qdo5i3gmg7bgjbtvlb0mzgcq and more conversations can be found on Slack: https://openmainframeproject.slack.com/archives/CC60ALD61/p1536166660000100

BrandonJenkins14 commented 5 years ago

This issue is hard to track from my perspective. Does anyone have a status update on if new doc site designs are proposed/being worked on? I know onboarding squad meets regularly to sketch out persona paths, and there is an extender-1.0 branch in this repo with changes in progress.

I still see an issue where Zowe Application Framework is being discussed in detail in the user guide from a developer perspective. The "Using Zowe Desktop" section looks great, but I think that "Extending Zowe App Framework" will belong in an Extenders/Devs section.

nannanli commented 5 years ago

@BrandonJenkins14 I have a proposal to reorganize the site here: https://github.com/zowe/docs-site/tree/docs_reorg. However, with the ongoing discussions from the onboarding squad to define Zowe 1.0, we'll need to work closely to understand what works better for users and redesign the doc site flow and structure. I'll meet with Tim/Joe this week to see how we can move forward. Stay tuned. :-)

nannanli commented 5 years ago

A quick status update for this issue: We're collaborating with the on-boarding squad to reorganize the topics and sections on the doc site. After the new structure is set, we'll proceed to change the organization and add missing topics if any.

nannanli commented 5 years ago

In 0.9.4, we rolled out the new organization based on discussion. Check out the doc site. We have much further work to do to improve the current organization like adding new topics and improve navigation of several sections which we can open new issues to track. Therefore, closing this issues now. Feel free to reopen if any problem persists. Thanks!

zowe / docs-site

Overall doc organization #36