Software Engineering
documentation repository development-environment
Updated Mon, 01 Aug 2022 00:22:40 GMT

README "Setup" section best practice?


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?




Solution

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.







External Links

External links referenced by this document: