Adapt Learning Community: Improving the authoring tool installation

At times, the forum gets a bit overwhelmed with authoring tool install-related issues. While we've committed to creating 'easy installers' for v1.0, this won't come for considerable time. This doesn't mean however, that we can't improve the installation process we already have.

I'm keen to hear from anyone who's installed the tool (or tried and failed):

What areas do you think could be improved?
Were there any specific parts of the install you encountered difficulty with?
Any other related feedback you may have

What this post isn't:

A Q&A for users unable to install the tool. If you're having specific issues, please create a new post.
A requirements gathering for the '1-click install'-type utility for v1.0.

Some common issues that crop up time and again are:

Dependencies not being installed
Incompatible node versions
Proxy issues (mostly related to connecting to GitHub)
MongoDB connection issues

Show parent | Reply

Common suggestions collated from current feedback:

Video walkthroughs for install (particularly on windows platform)
More streamlined install process for non-devs (preferably with as little third-party dependencies as possible)
Hosted 'nightly' demo site

Show parent | Reply

When first installing I difficulty with :

Installing over a controlled network (proxies) - I had to tether my phone to use wireless/mobile data to install via github

Wrong node version (easy to fix with nodist but not if you have no idea what that is!

Understanding the instructions as a newbie (grunt? what?!?!)

Suggestions :

A video/pictorial walkthrough showing exactly what to download, install, open, type and click.

A troubleshooting FAQ with common errors and images of error message you may get etc

Show parent | Reply

Thanks Helen :)

There seems to be a requirement for a more fool-proof install (duh) for non-developers. This will mean possibly sacrificing some of the more dev-friendly utilities such as git repos however.

I think adding much more detailed error reporting during the process, as well as a more 'stepped' approach (i.e. not having to reattempt the install from the beginning if something goes wrong) will go a long way. Although it'll be impossible to guard against all possible configurations of network settings, platform dependencies and settings etc, there's a lot more we can do to try and guide people during install (or at least identify the source of the problem) - so users can help themselves.

Show parent | Reply

Hi Tom,

I've been considering this for a few days. I think the best improvement for both the framework and authoring tool would be to limit or roll back the number of inter-dependent tools required to install the software. As, for me anyway, install failures seemed to be the result of one tool trying to use another to install something. e.g., bower trying to pull from git.

Show parent | Reply

I'd tend to agree with this Greg. There are places in the install where we could be more minimal in terms of dependencies. This being said, most of these are in fact very useful for developers working on the tool (git in particular) - I wonder if we could introduce a production installer alongside the current.

To add to this: encountering any issues during install can be extra frustrating due to the fact that you're forced to begin the entire installation again.

Show parent | Reply

Here are three items that may help:

Specific video/user documentation for Windows users
- I think the installation is fairly easy... on anything but Windows. Having a specific, step-by-step video with accompanying documentation is critical to get that population of users.
- Troubleshooting tips, here's how to fix PATH issues, etc.
Eliminate extraneous information from the Wiki
- I know we have only one wiki site, but migrating the contributing, plugin development, etc information to a completely different location may make users less confused with the process.
Eliminate the installation all together and provide users with a demo site (refreshed daily) to try out
- Get them hooked so they can push on through the installation process

Show parent | Reply

Some really good points there.

I think the 'nightly demo' idea would be something that would really help the project - I'm sure we've scared off users who haven't even been able to see the tool in action.

Show parent | Reply

Hi,

I'm thinking it might help to provide a little more information/context for new users in the documentation and install instructions. While this may not actually improve the install itself, it may reduce some of the confusion or frustration that some new users might have.

For example, I think the typical user probably gets to adaptlearning.org from Google or from some other site like this one. They check out the demos and think "wow, this looks great!". Then they do some poking around until they get to the install page, thinking "ok, I'm gonna download and install a Windows .msi and start building a course!" In other words, I don't think many people are going to understand:

That this is a server based install. You don't install it on every author's machine and send the files back and forth, you install it centrally on a server/VM and all authors log into it in a browser. If users who have access to an IT department and VMs know this in advance, they might be more likely to reach out for help from the start if it's a little more than they're comfortable with.
The distinction between the framework and the authoring tool. Which one do I pick?
The authoring tool is still a 0.1 release. Yes, you should try it out, it's awesome and it's constantly improving...but maybe don't use it for that absolutely critical training course your CEO asked you to publish by next week.

Considering the current state of the project, the install really isn't that rough compared to other server-based solutions I've installed in past. Always room for improvement of course, and you don't want to scare people away, but coming in with the right expectations might actually make users a little more resolute to make it through that install. My two cents, anyway.

Cheers,

Ryan

Show parent | Reply

Thanks for those encouraging words Ryan!

I think it is important to take a step back and look at everything in context -- while we're working hard to get to a 1.0 release, we a long way away.

I think your advice around informing potential users is vital when it comes to managing expectations. On this note, we're currently redesigning our entire web presence to make it much easier to find relevant information about the project, particularly when it comes to enticing potential users of the framework/authoring tool. I'd agree with you that at the moment, it's quite confusing for any newcomers.

Show parent | Reply

Hello Tom,

I knew about Adapt two days ago and as I found-it very interesting I tried to install the authoring tool to my windows 8.1 computer. And that was hard...!

I used the virtual box method, that always crashed with a timeout during the Vagrant installation. Until I found that the Virtual box was unable to create an Ubuntu 64 bits. After may searches on the web I found I had to modify my BIOS, to enable Intel virtualsation...

Finally it worked and I was able to open Chrome and do the famous localhost:5000 to enter into Adapt authoring tool.

I created a first one page test, but when I download-it and try to run it from my desktop... just the blank page!

I would like to see the files and others where the module is stored... no shared folder on Windows and impossible to log into the virtual box adapt drive, as I do not have the login for the installed Ubunto...

A bit hard, but I'm sure I'll find the answers.

To avoid that kind of frustration, it would be fine to have a support page or elearning module or pdf or anything else with:

On which OS Adapt (authoring tool and framework) can be installed
A schema for each installation and alternatives (i.ex. Virtual box or directly in Windows?, installing in an Ubunto desktop...?)
Precautions for each installations
Where to find the projects directories
What can be wrong and how to correct-it
...

I know adapt team has already done a hard work trying to simplify our job, but we are not necessarely computer specialists!

Tnanks a lot,

Claude

Show parent | Reply

Hi Claude,

Thanks for your feedback, and these are good points.

Windows, and its various versions (7, 8.1, 10) has taken 95% of the time the team has spent dedicated to resolving Vagrant installation and setup issues, and we're still not where we want to be. It's fair to say there are a lot of (sometimes quirky) variables that come into play when running a Vagrant server image a on Windows, such as the BIOS issue you've mentioned.

The software is intended for running as a service on a server, and runs very easily on Ubuntu or OS X.

We would absolutely welcome any assistance from the community of Windows users with regards to ironing out the Vagrant issues.

Brian

Show parent | Reply