Thanks Robert, 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 <[email protected]> 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. 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. 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 ? > > > ** 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). > > > 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. 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. > > > Thanks for your time in reading this. > > Thanks for the report. > > Regards, > Robert > > > Regards > > Vineet > > [1] > https://access.redhat.com/documentation/en/red-hat-container-development-kit/2.1/release-notes-and-known-issues/#vagrant_compatibility_matrix > [2] > https://access.redhat.com/documentation/en/red-hat-container-development-kit/2.1/single/installation-guide/#additional_software_requirements_for_mac_os_x > [3] > https://access.redhat.com/documentation/en/red-hat-container-development-kit/2.1/single/installation-guide/#installing_virtualization_and_container_development_kit_components > [4] > https://access.redhat.com/documentation/en/red-hat-container-development-kit/2.1/getting-started-guide/#preparing_host_system_for_using_openshift_from_the_command_line > >
_______________________________________________ Devtools mailing list [email protected] https://www.redhat.com/mailman/listinfo/devtools
