Remove dev_guide/console, move info to arch/mgmt_console & related topics.

[adellape]

@CowboysFan @bfallonf @tpoitras @tnguyen-rh Looking for feedback on this idea.

This is an effort to re-focus/re-frame the dev_guide/console more clearly as a "Navigating the Management Console" topic. The topic already showed basic nav + filtering/searching, but this changes the console_navigation.png screenshot to show the Overview tab (instead of a close up of the Browse tab), and adds callouts for the various parts of the console at a glance. The callout descriptions provide links to the respective task-based sections/topics.

Here's a full build (internal) for convenience / link hopping:

http://file.rdu.redhat.com/~adellape/042915/navigate_mgmt_console/dev_guide/console.html

I'm hoping that this balances the line of providing a simple, high-level early tour of the console (as well as basic nav / filtering info), while also passively guiding readers to the task-based topics (as mentioned in #314 (comment)) with the various context links.

Continuing with this idea, for example where callout 6 (about the Browse tab) links to Builds, Deployments, etc, I could then go into those topics and add screenshots to show the visualization of those resources in those various topics.

Note that I did not change the dev_guide/console filename, so as not to break internal refs, or links in the wild (e.g., the OpenShift blog linked to it the other day, though I realize we could just get that updated there). And I renamed the old console_navigation.png as console_services.png, since it shows the Browse --> Services info pane, to in theory be moved instead to a section more specifically about services.

cc @bparees @sosiouxme

[bparees]

i like the concept here (but i guess i better since i was one of the instigators in the other PR)

thanks @adellape !

[adellape]

Closer to GA we could also record a tour video to put in the Overview section, too, maybe.

[Bilhar-rh]

@adellape This is good, and this is basically what I had done in the v2 docs way back in the User Guide. However, I'm sorry, but it didn't make much sense then, and it doesn't make much sense now. I haven't had any cases where people are saying they don't know how to navigate the console, and they would like docs around it. Also, if we have a console topic in the Dev Guide, then it calls to reason that we should have something about the CLI. Therefore, I still stand by my case that this information should be embedded in the console itself, and you should not have to read a topic to learn how to simply navigate a web interface. I've reached out to @jwforres about this to see how much of this is doable, and I'll work with that team to try and achieve this goal. So, for now, I wouldn't spend too much time on this, and I think we should stick to the original plan where any task that can be done with the console will be documented in that particular section. If the console grows to where you can do everything there that you can do in the CLI, then we'll create a separate topic category just like the CLI. Thanks.

[Bilhar-rh]

@bparees Can you do everything in the console that you can do with the CLI? Maybe that's the question we have to answer better, because if you can then we can simply move all this into its own topic category. But if you can't then we'll stick with the original plan until the console gets to that point, or until we can put some of this stuff right into the console itself as I mentioned before. Thanks.

[bfallonf]

@CowboysFan @adellape I'm thinking this is a good idea to have in the docs. Maybe it's better to look at this with the view of "I'm not sure if there's a reason why this shouldn't be there", rather than "People aren't asking for this". If we have reference topics (eg, We have the X Feature and This is How it Works) in the docs right now, there's no reason why we shouldn't be documenting all features.

Sure, having more information on the console itself would be good, but, in saying that, people can just use "osc --help". It's the same argument: if they can get their information somewhere else, then why go to the docs?

Also, taking a glance at docs from other teams that have console/gui/things, they have a section outlining the console, if only a high overview of the point it serves. They may have consoles with more involved processes, but this is only the first iteration of ours; it's bound to get more involved.

Those are my two cents...

[bparees]

@CowboysFan no, of course the console is not likely to ever do everything the CLI can do. I guess my concern is that, absent actually seeing this "task based structure" i'm worried it's not going to be obvious to quickly find the workflow i'm looking for in a giant list of things i might want to do. A quick high level trip through the console might help get me pointed in the right direction faster than clicking through a series of detailed task flows.

In fact, the fact that the web console can do so little, relative to the CLI, at least for now, makes an argument to me that it's more important to provide a specific guide to what can be done in the console.

If everything could be done in both places, i'd say there would be less of a need for it.

[Bilhar-rh]

@bparees I understand your concerns, and these were brought up for v2 content, but customers really never complained about it. I took that content out of the v2 User Guide for the exact same reasons, the console was limited. The Dev Guide is intended for developers to create applications, and making it task focused really is how we do all our content. Also, we make many assumptions that are far more challenging than people figuring out how to use the console for some basic tasks. And we will indeed have those tasks documented in their respective sections, where applicable, so we're not completely abandoning the console content, yet. Considering our audience, the content we have so far really is self-explanatory, just as it was for v2.

I really want to move in a forward direction rather than backwards, or what we've been doing in the past. It may be aggressive, but I really want the console to have context-sensitive help for this basic navigation stuff, and maybe more. From a content strategy point of view, that's the direction I want to go. Even if it takes a few iterations to get there, I think we must strive for it. Creating separate docs for a web GUI I think is not the correct approach, and I felt this with the v2 stuff as well. Let's see what @jwforres says in terms of how much we can achieve.

But I think it would be cool that you can just hover over Settings and a pop-up window displays what you can do with that. I'm sorry, but I feel very strongly about this.

[bparees]

@jwforres probably won't be saying much :)

Anyway ok, i've made my case, you guys own this stuff so you do what you think is best.

[adellape]

@CowboysFan What if I reworked/rephrased it and moved (at least) the Overview image (and all the callouts) to the Architecture --> Infra Components --> Management Console topic?

http://docs.openshift.org/latest/architecture/infrastructure_components/management_console.html

Since it's just a place to describe what the Management Console is.

[tpoitras]

This is an interesting debate, and I can see the logic to both sides. Having played with the Management Console a bit lately, I do think it's important to have a high-level overview of what's possible using it. It doesn't have to have enumerated steps describing how to do each task. This section could be extremely short. I think what Ben said has a lot of merit, the part about it "not going to be obvious to quickly find the workflow i'm looking for in a giant list of things i might want to do."

While we probably don't need a separate guide, I think it's worth writing about the reasons you'd use the console, and the benefits to the user vs. the CLI.

[Bilhar-rh]

@bparees @adellape @bfallonf @tpoitras @tnguyen-rh I think there may be a huge misunderstanding or miscommunication here after talking with Brice and Tim. Please note that I'm NOT talking about removing the management console altogether, or from the Architecture topic dir, just the topic in the Dev Guide because it doesn't serve much purpose. Apologies for any confusion here.

@adellape I'll look into this a bit more next week, so let's leave this open for now. Putting this content in the Architecture dir may be a bit out of place in my opinion. Showing people how to use the console probably doesn't really belong in Architecture. One thought I have is that originally I had a topic dir that covered all the interfaces, management console being one. Maybe it makes sense to reintroduce that, and that's where this content would fit in, but only until we get all this to be a part of the management console. I'll look into it next week. Thanks.

[adellape]

@CowboysFan @bfallonf @tpoitras @tnguyen-rh Updated this based on our chat last night. The basic gist is:

1. Removed the dev_guide/console.adoc file, and spread its contents to other topics, such as...
2. Moved the map of the Project Overview screen to the Arch topic. Kept it short and sweet, and serves to link readers visually to related topics where they can find task-based info. See http://file.rdu.redhat.com/~adellape/051315/navigate_mgmt_console/architecture/infrastructure_components/management_console.html for pretty build.
3. Moved the part about using the Mgmt Console to select projects from dev_guide/console into the dev_guide/projects topic inline with the related CLI commands. See http://file.rdu.redhat.com/~adellape/051315/navigate_mgmt_console/dev_guide/projects.html for pretty build.
4. Also moved the "Filtering by Labels" section & images to the same topic from dev_guide/console into the dev_guide/projects topic.

Let me know what you folks think of this idea. I think it serves the purpose well enough during this meantime while Bilhar is working with the UI team to get more info embedded into the Mgmt Console itself, and we could revisit things in the future.

N.B. The project overview page has already changed quite a bit since I took some of these screenshots, and has more changes upcoming. If we merged this, I could wait until after code freeze then update the images again.

[bfallonf]

@adellape @CowboysFan I like the placement of the Console stuff now. I do think this is better than a section in the Dev Guide. And I think the additions to the architecture/infrastructure_componenets/management_console.html are an improvement to the info that was there already.

Overall: gold star.

[tpoitras]

I definitely think is the right placement for this sort of information. Good stuff, @adellape :) 👍

[adellape]

Thanks, @bfallonf @tpoitras

@CowboysFan Can we get a thumbs or down on this to move along either way?

[Bilhar-rh]

@adellape Two thumbs up!! I think it's much better this way until we figure out the long term plan. Good work, and thanks for taking care of this!

[adellape]

Merging this for now. Will update screens after codefreeze. We can also update dev_guide/projects to mention creating projects from the web console (a recent addition).