Hi,
On Mon, Aug 1, 2016 at 4:28 PM, Vineet Reynolds Pereira <[email protected] > wrote: > 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: > > +1 for better way. > * 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. > If it is really creating issues in up and running CDK then we should document appropriate VirtualBox versions too. > >> > * 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). > Plan is to implement CLI approach to install the client binaries for OpenShift client tool(or other services) running inside the CDK through command(Mac/Linux) or hook with Devstudio for Windows. This will be part of upcoming CDK 2.2 release. > >> > 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 > > Thanks for your valuable suggestions Vineet. Regards, Budh Ram Gurung Software Engineer - Dev Tools
_______________________________________________ Devtools mailing list [email protected] https://www.redhat.com/mailman/listinfo/devtools
