4

In the SETUP section of my README, should I just link to instructions for each dependency like this:

STEPS

  1. install Appium (guide)
  2. install XYZ (guide)

Or should I reproduce all their instructions here, instead of the links?

Their instructions are out of date. For example, Appium tells you to install Ruby 2.1.1, and then install the latest appium_lib. But the latest appium_lib now requires Ruby 2.2.x - so should I just list those errata following the link? Or should I paste their steps here and just fix the issues I found?

  • Not answer worthy, but I agree with the general idea that links are sufficient. If information is outdated, I'd personally also let the devs of these dependencies know. I know I like to hear it when people find outdated pieces of information in my work. – Joris Meys Jun 16 '17 at 10:09
2

In general

If you refer to well documented products, the safest would be to provide a link to the original instructions as you did: these should always be up-to-date, and address the many platform specific issues.

This policy is the same as for the code and libraries: if a library provides a function or a class, you'd in general use it as it is and not rewrite your own tailored-down one.

But...

But the world is not perfect. So there are at least 3 exceptions to this policy:

  • the original component is not well documented (e.g. obsolete or misleading docs)
  • the original repository is not stable (e.g. frequent change of documentation url, or version specific url): your link might quickly get broken
  • your code is deeply dependent on a complex component, and you offer guarantee to your users only for a specific set of versions (and this is why semantic versioning matters).

There is another exception, but a pragmatic one: if the instructions are really trivial (e.g. install a package, or download installer and follow the instructions) you could as well provide the instructions directly. Users will appreciate, as they won't have to browse through kilobytes of documentation just for finding such trivial instructions.

3

Honestly this is where a lot of opinion and policy is going to come into play. However the goal is the same. You setup instructions should contain enough information that any idiot can setup the project. That's important, because it's not just people that are used to the tool chain that are going to need to setup the project. There will be, at some random point in the future, someone that has no idea what there doing but has some control over the budget, that will want to "take a look".

So I usually set these goals.

  1. Use tools to setup the project where ever you can. For example, instead of a list of gems just use rake.
  2. Make sure setup is "one step". For example rake setup. Then add the parts to that. So bundle install, rake db:migrate, thing do-what's it, whatever. This isn't always possible as it means rake has to work, so you have a chicken and egg.
  3. Resolve chicken and egg with instructions to make a chicken. For example, "You must have a sane working environment to setup this project, please see (link to website here) for instructions on how to install (working environment here). Now it's important to keep this "chicken" as simple as possible. So in the Ruby example, instructions to setup ruby, rubygems, rake. Then hand off the process to rake setup.

The reason links are bad is the same reason there bad on Stackexchange. They won't always be there. However this is less of an issue, because you can edit the read me (and should be) frequently. So if someone says the "install ruby instructions" don't work then you can just swap out the link.

The reason big blocks of text are bad is because there just isn't a need. 90% of your "audience" will never look at the read me. Specially if you have rake setup going. Then know how to setup ruby, ruby-gems and rake, and they don't need your instructions to do so. What they might need is a quick list of odd dependencies. And for that, a list with links to instructions is great.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.