[Devtools] Installing CDK - some issues noted

Mon Aug 1 11:40:05 UTC 2016

On 1. 8. 2016 16:28:18, Vineet Reynolds Pereira wrote:

> Thanks Robert,

Hi Vineet,

> I went through the docs again - they are the same ones you reference. So,
> my suggestions and feedback will a bit more specific, which is inline.
> 
> On Mon, Aug 1, 2016 at 2:31 PM, Robert Kratky <rkratky at redhat.com> wrote:
> 
> > On 1. 8. 2016 13:53:36, Vineet Reynolds Pereira wrote:
> >
> > > Hello list,
> >
> > Hi Vineet,
> >
> > From reading your post, I'm thinking there's some confusion with regard to
> > CDK docs. Could you please specify what docs you're referring to?
> >
> > Official CDK docs are at
> > https://access.redhat.com/documentation/en/red-hat-container-development-kit/
> >
> > >    I tried out CDK 2.1 on a brand new Macbook, to test drive the
> > > installation experience. An installation was also attempted on a Linux
> > box by someone in my team; he eventually installed CDK on a Debian host
> > insTead of a RHEL 7 VM on the same host. I'll focus on Mac, since we're
> > looking at Windows and Mac users primarily. There are some suggestions to
> > improve this experience.
> > >
> > > * Vagrant version issues (Mac)
> > >    I started with Vagrant 1.8.5 (the latest), then ran into this bug with
> > > SSH keys [1] when bringing up the CDK vagrant box. Tried downgrading to
> > > 1.8.4, and ran into this one [2] involving installation of local gems
> > > supplied by CDK. Ultimately, I downgraded all the way down to 1.8.1,
> > > because the CDK version "appeared" to have been tested against it.
> >
> > Our Release Notes contain a Vagrant compatibility matrix [1] that tells
> > users to use 1.8.1 or 1.7.4 on Mac. The Installation Guide contains this
> > info in relevant places [2].
> 
> Ok, I think we need to find a better way to present this, and I would
> suggest getting in touch the UX team. My onboarding workflow was like this:
> 
> * Search for RedHat CDK and land at
> http://developers.redhat.com/products/cdk/overview/
> * Get started with the call to action button and land at
> http://developers.redhat.com/products/cdk/get-started/
> * Start the installation for Mac as indicated in the tab:
> http://developers.redhat.com/products/cdk/get-started/#tab-macLinux
> * I expected to see the versions here, since the page already talks about
> installing Virtualbox and Vagrant. In fact, it talks about Vagrant 1.7.4
> for RHEL, but nothing about the Mac. This is probably where the troubles
> started, and I think a pre-requisite matrix would help here.
> * It only later that I land at the pages delivered as part of product
> documentation, from the getting started page.

I see this as the main problem -- users come to dev.rh.com and follow the instructions they find there. Some of them may not even reach the regular docs that are only linked from there.

It doesn't matter how complete are the regular docs when the 'get started' stuff on dev.rh.com is insufficient or inconsistent with other instructions.

As you correctly point out below, the docs team doesn't own the content on dev.rh.com, so we're in a difficult position. I'll try to work with Lincoln, the editor of dev.rh.com, to figure out a way to improve this experience.

> A specific comment on the Vagrant 1.8.1 pre-requisite noted in the docs -
> the version should be emphasized, and that's why I couldn't remember where
> I saw it first. It easy to gloss over that entire paragraph, because other
> parts of the page are bolded and made to stand out as more relevant. I
> think a bullet list of pre-requisites would be better, separated from other
> text would help. Someone from UX can help you more by revisiting the
> onboarding flow listed above.

For my part, I'll make sure to emphasize the version info in the regular Installation Guide.

> Generally speaking, the entire navigation flow allows for installation to
> fail because the important parts like pre-requisite versions are brought
> out much later in product docs, or they're not emphasized enough over other
> information. My point is not that documentation is bad. Developer
> experience is bad. I know, we as a company don't commit the obvious mistake
> of not documenting the necessary, but to our end-users the same information
> can be hard to find.
>
> > > * Virtualbox version issues (Mac)
> > > Vagrant 1.8.5 supports Virtualbox 5.1.x (latest) [3], but on downgrading
> > > vagrant to 1.8.1, it proceeds to download Virtualbox 5.0 when bringing up
> > > the Vagrant box. Vagrant fails to download and install Virtualbox for
> > > some reason (I didn't bother to debug any more vagrant issues at this
> > > point), and went and manually downgraded Virtualbox to 5.0.26. That's
> > > three downgrades in one installation session.
> >
> > I wasn't aware of any VirtualBox-version restrictions. I'll work with QE
> > and update the docs with this info.
> 
> It's a dependency for Vagrant as as vagrant provider, so sometimes Vagrant
> needs to support newer versions of Virtualbox in newer Vagrant releases. It
> needs to be addressed in the navigation flow, but yes, this needs
> revisiting from QE every release for the test matrix.
> 
> > > * Documentation for Linux users
> > >    I'm a bit lost on this area, since there might a product direction I'm
> > > unaware of. I see that the documentation references Vagrant+VirtualBox as
> > > something that can be installed on any Linux OS, by talking about deps
> > > and rpms. But, the rest of the documentation is specific on RHEL 7 Server.
> > > I have a few open questions here -
> >
> > As I said before, I'm not sure what docs you've been following. Our
> > Installation Guide instructs users of RHEL to use libvirt/KVM, not
> > VirtualBox [3].
> 
> Ok, going by the navigation flow, it looks the the Getting Started page at
> http://developers.redhat.com/products/cdk/get-started/#tab-macLinux
> needs to have all of this info. It allows Linux users (RHEL is Linux) to
> bring VirtualBox and use it, and the docs do not address how to use this
> vagrant provider later, instead driving the user to libvirt. I believe this
> particular page is not owned by docs, and I'm not faulting anyone for this,
> but the overall experience to end users is disjointed.
>
> > >      ** Why is there focus on RHEL 7 Server, when developers on Linux are
> > > unlikely to use this for day-to-day development tasks? For someone using
> > > Ubuntu or Fedora with Virtualbox, the Linux docs are only partially
> > > useful, given they address libvirt on RHEL 7.
> >
> > For CDK 2.1, RHEL was the only supported Linux distro. For previous
> > versions, we had instructions for Fedora as well, but they had to be
> > removed. I'm hoping that support for Fedora will be reintroduced in CDK 2.2
> > -- and then it'll be documented again.
> 
> That would be great to not have that regression in supported OSes.
> 
> But what about other OSes? Are we going to tell developers to install
> RHEL/Fedora when their work OS is a different Linux distro, or is this
> going to be left to the community(ADB) to address ?

I suppose we can't realistically support 'other' distros, but if it's requested, we can at least document generic instructions for RPM and DEB-based distros (with big warnings that such installation paths are unsupported).

> > >      ** Is there any open issue to ensure we address other prominent
> > >      Linux distros?
> > >
> > > * OSE client (oc executable)
> > >    The documentation on obtaining the OpenShift client, is present in an
> > > RST in CDK.zip, but not in the docs. I think this was discussed
> > > previously in some other thread, but I thought I'd mention it again
> > > incase it wasn't.
> >
> > The Getting Started Guide includes detailed instructions on how to obtain
> > the 'oc' (and 'docker') clients [4] for all platforms.
> 
> I missed making a suggestion in the original mail. Did we explore about
> packaging OpenShift client tools as part of CDK zip distribution itself?
> That would be great and I don't see why we shouldn't (licensing concerns et
> al).

This is being discussed for the next release (not bundling but automating the download). Whatever the preferred solution ends up being, we'll document it.

> > > Suggestions follow:
> > >
> > > * Publish the testing matrix prominently on what versions of
> > > pre-requisites users need to get CDK up and running without issues.
> > > If it's already written down somewhere, it needs to be prominent in
> > > the installation pre-requisites section of the doc.
> >
> > See [1]. Also, install. instructions for each supported platform tell
> > users exactly which versions to use. For example, for Mac, it's at [2].
> >
> > > * Have nightly builds against our OS targets and possibly multiple
> > > versions of pre-requisites, so we know about issues involving pre-
> > > requisites even before our users do.
> >
> > Nightly builds:
> > http://cdk-builds.usersys.redhat.com/builds/nightly/latest-build/
> >
> > > * Expand the documentation for Linux users, and bring in clarity on
> > > multiple vagrant providers. If we are going to support only libvirt usage
> > > for Linux users in our docs, we should declare this as a pre-requisite.
> >
> > I'll be happy to work on improving the docs, but I'm pretty sure you're
> > talking about some other docs than the official ones. I'm really keen to
> > find out where the problem is, so that we don't have this confusion.
> 
> Atleast to me it's now obvious that we need to work with our UX team on
> this. developers.redhat.com is where developers are onboarded and driven to
> the production docs later. And they're owned and updated by two different
> teams. I haven't seen the designed navigation flow in entirety, but it's
> obvious that developers.redhat.com expects (or would expect in the future)
> certain hooks in production documentation so that it can link users to the
> right information at the right time in the installation task flow.

Agreed. As mentioned above, I'll work with the dev.rh.com people to fix this.

Regards,
Robert

> Additionally, we have to do design critiques as part of our development
> process (slide 45 @
> http://www.slideshare.net/CatherineRobson/user-experience-bootcamp-for-developers)
> to spot out the obvious UX mistakes. I'm leaving it open on who does this.
> But it needs to be done.
> 
> There is of course a different matter that we're expecting developers to
> download multiple third-party bits and install them. There's a legal angle
> to that, but our end users will need a gap experience when coming from
> docker-machine and other equivalent tools.