pytoutv icon indicating copy to clipboard operation
pytoutv copied to clipboard

Published 20 hours ago • verified publisher icon bvanheu

Simplify READMEs

Open eepp opened this issue 9 years ago • 5 comments

pytoutv READMEs are really huge.

I suggest minimizing them the following way:

  • move the top public API/CBFT-DT disclaimer stuff to a new Disclaimer section at the very bottom of the README
  • remove historical note about Tou.tv-console-application: it's been more than one year now, and people do not remember/care about the dark ages :wink:
  • fix the Mac OS X section (incomplete Markdown)
  • remove Using setup.py section: not needed since people will almost always use the pip method, which is simpler
  • remove Library section: not ready yet anyway
  • replace heavy CLI examples by asciicasts, which also shows colors
  • remove Bugs and Contributing sections: it's pretty obvious that GitHub issues/pull requests are the preferred ways to contribute
  • rename Python workflow section to Developers (or Contributing, again)
  • remove Semantic versioning section: users do not really care about that, it's only for developers
  • remove Contributors section: contributors are available in the [https://github.com/bvanheu/pytoutv/graphs/contributors](contributors section) of the project

eepp avatar Apr 01 '15 05:04 eepp

It all makes sense.

simark avatar Apr 01 '15 11:04 simark

I don't know if there are already good ways to do it, but a section that shows the best ways to use the toutv client in a script would be cool. It could show a small script that downloads the latest episode of a show, which you could put in a cronjob. Of course, it would have to not re-download the same episode over and over.

simark avatar Apr 01 '15 11:04 simark

A complete Sphinx documentation of the toutv package would be needed, within which examples can be inserted.

eepp avatar Apr 01 '15 14:04 eepp

~~I suggest we keep the README for developer things. We could have a doc/ directory with a user manual & dev manual (in asciidoc/markdown/*). Also we could use the doc as github pages?~~

~~Edit: or maybe a section on how to quickly get started~~

Please bare with me, I live in a unix shell.

Keep the landing page to user friendly doc, and more obscure stuff elsewhere.

bvanheu avatar Apr 01 '15 21:04 bvanheu

Well, since the README.md file corresponds to the repo/project's landing page, I would prioritize documentation for users here:

  • what is pytoutv?
  • features
  • how to install on various platforms
  • a few asciicasts

I would put everything else in the repo's wiki, with a link to the wiki in the README.md files.

eepp avatar Apr 01 '15 21:04 eepp