Installation

[ms609]

As part of my JOSS review, I've attempted to compile TREvoSim 3 on Windows 10, following https://trevosim.readthedocs.io/en/latest/requirements.html https://trevosim.readthedocs.io/en/latest/requirementsinstallation.html

Overall my main impression is that the installation instructions assume that a user is already experienced in using GitHub and creating C++ binaries. My sense is that few users of the software will have this background, and that the documentation would be more useful if it assumed minimal programming experience, at a level that might be expected of a typical quantitatively-able graduate student in palaeontology/evolutionary biology.

Ease of navigating the documentation

• [x] I would place the links to the binaries before the details on installing from source. I imagine that most users will be looking for the binaries than the source; developers may be less daunted if they have to dig deeper into the docs. My first impression from the page was that building from source was the only option.
• [x] I suggest putting instructions for the latest version before those for legacy versions. I got half way through following the instructions for installing v2.X before realising that these weren't the instructions for installing the latest version. I presume that most users will want to download the latest version – if there's a reason for users to install older versions, it would be useful to include a brief decision tree on the install page, so a user can make the appropriate decision
• [x] It's not clear why Windows contains instructions for v1 and v2, but other OS don't. This leads to an inconsistent structure of subheadings, making the page harder to navigate.
• [x] I suggest simplifying the level 4 headings to simply contain the version number (i.e. "Installing version 3.X") – I found the other content in the header confusing

Installation from binaries

• [x] Please provide links to the binary files (or at least directions of where to find them) in the documentation pages.
• [x] Also consider linking directly to the binary files in README.md; the link in "TREvoSim can be installed and installed/run from the binary releases on our [GitHub]https://github.com/palaeoware)." does not contain an obvious route to locating binaries.
• [x] Consider making the installation instructions self-contained (or at least make it clear where the installation instructions can be found), so that a user who has been provided with the ZIP file has all the information necessary to complete installation.
• [x] I confused the v1-3 syntax with a version number. Suggest using an en-dash – rather than a hyphen – or rewording, to make clear that this is a range.
• [x] Once I'd located the binaries, the software ran "out of the box" with no further configuration required. Fantastic!

Installation from source

• [ ] Are there alternatives to QT for users who do not wish to create an account and subscribe to the daunting terms of service, or who do not have administrative privileges on their device?
• [x] Consider linking directly to https://www.qt.io/download-qt-installer-oss . The main download page provides 10-day trials, with a small and ambiguously worded link to the open source version, which itself doesn't contain obvious installation instructions. This may be offputting for potential users.
• [x] Consider specifying installation configuration settings for Qt. The installer's default setting is "custom installation", which is unclear. This left me unsure whether I would need to select any components at the "Select Components" stage.
• [x] Include a link to the source code alongside the instruction "Download source code"
• [x] I interpreted "open a new project" as directing me to click the "Create project" button. Suggest rewriting to "Select "Open project" and navigate to ..."
• [x] I gave up at step 5; I don't know what configuration might be necessary or what the standard debug/release procedure might be. When I ran Build→Run CMake I saw errors that I couldn't immediately diagnose.
• [x] It would be useful to also give complete instructions in step 6. What modifications might I need to make to the inno_setup file? How do I determine which DLLs need to go in the bin folder? etc.

[RussellGarwood]

Amazing, thanks so much for these pointes @ms609. Will work on this very shortly, and tick off the items in your list as they are addressed. Where requried, I will respond in italics

[RussellGarwood]

@m609 - all the above points are now addressed bar one (see below) - I'll leave the comment open for a day or two in case you want to check any of the above out, and if I hear nothing further, then close it.

-- Are there alternatives to QT for users who do not

To an extent, yes. You do not need an account to use on an open source OS, so if those T&Cs are an issue, this would be the solution (although I recognise that may not be convenient). Long term, my intention is to replace all QT datastrctures and classes in the core simulation with STL C++, allowing me to compile a headless version for command line use (which relates to issue #31 ) - but that will be in a future release

[ms609]

Looks good to me! 👍🏾