Instructions in the README
rougier opened this issue · 6 comments
I'm testing installation and there's a small typo:
cd bruker2nifti-master -> cd bruker2nifti
For testing, you indicate nose but you do not explain how to use it and what should be the expected results (are there skipped tests, known errors, etc.)
For installation instructions, it is not clear that you provide alternative instruction for installation. Because of the structure of the README, it's like every step I necessary. Maybe you can have a main "installation" header and sub-headers for each installation (with a small introduction explaining these are alternative ways for installation).
For the non programming method, if would be good to provide the direct link to download the last release. For non programmer, it might be difficult to navigate the GitHub interface to find the right file. Also, the zip archive of the repo and the zip of the release are not really the same, you may prefer to use the "stable" release only since the current repo might be unstable.
For the initial description, could you add link to "Brukert ParaVision" and "nifty" ? It might be good also to explain things a bit more (what is the target audience, why it is necessary, real for example, etc.)
Really agree this part requires some improvements. Also there were too many redundancies between the wiki and the README.
I tried to make it more clear while removing redundancies.
Also, do you need the virtual environment at all ? I tested it using the git clone/ install -e and it works fine. I found the virtual environment a bit confusing since you do not really explain how to use it (apart from the given link).
Uhm, lets say that are warmly suggested. Going into details of the virtualenv can be a bit of an overkill. And could not do it better than The Hitchhiker’s Guide to Python linked.
It is now a parenthesis for the curious reader. Let me know if it makes more sense.
@rougier: Hi,
Due to the redundancies between the wiki and the README I did some documentation refactoring.
The informations are the same, probably more accessible and less repetitive. If you have a spare minute let me know if you prefer it now.
Yep, definitely nicer. By the way, I recommended you submission for publication (I didn't manage to mention you using the @ notation). Only remaining issue being the new version to replace the old one and the automatic building of the PDF (very minor issues).