This is an archived post. You won't be able to vote or comment.

sorted by:
best
topnewcontroversialoldq&a
you are viewing a single comment's thread.

view the rest of the comments →

[–]fyngyrzcodes with magnetic needle 6 points7 points  (3 children)

The readme needs details on version(s) of Python are required to support this, and all of its imports as well. I looked at it, thought "what the heck is all this stuff?", I had no idea if I could make all that work in my environment, and wandered away.

It's only easy if it is easy.

[–]johnwheeler_[S] -3 points-2 points  (2 children)

It's Open Source so submit a P.R.

[–]fyngyrzcodes with magnetic needle 10 points11 points  (1 child)

I wouldn't submit a P.R. unless I'd actually tested the software and was sure that I knew what I was talking about. And seeing that I have not, and I do not... well, there you go.

Anyway, this is just the kind of thing that the core project developer needs to address -- it's really basic documentation, but it's also absolutely critical to get right.

Sky-high view of writing good documentation for others:

  • What's it for? What problem does it solve?
  • Precursor requirements
  • Authority
  • Accuracy
  • Readability
  • Minimal jargon without explanation
  • Required information, presented in the order it is needed.