Improve & expand documentation

[ix5]

Isso's docs have grown over time and some instructions have become outdated. Other parts lack needed info or are just not very inviting to newcomers.

Main problems

• Information scattered over code comments, README, docs, (old) GitHub issues
• Contribution guidelines are unclear to some people. @Guts complained about this in IRC and there should be some guidance on what kind of changes are favored and which will be rejected
• Several configurations mentioned in Deploying probably haven't been tested in years

TODOs

(Not every item in this list must/should be addressed, this is just an overview of possible improvements)

• [x] Expand README, which serves as first point of contact for many people new to Isso
• [ ] Expand FAQ
• [x] Review (obsolete?) tech such as Vagrant, Ansible, uWSGI whose configs might no longer work and investigate removing them
• [ ] Deployment:
  • [ ] Add more deployment options such as Heroku, Vercel and investigate one-click installers for some SaaS platforms
  • [ ] Create current working Apache config, mention alternatives to nginx
  • [ ] Remove old/invalid references (e.g. ancient bugs in uwsgi/gevent)
  • [ ] Add example Content Security Policy (CSP)
• [ ] Expand Troubleshooting with more common errors (survey GH issues for common culprits)
• [x] Overhaul contributing section
  • [x] Point out more ways to contribute
  • [x] Link to "contributor-needed" label
  • [x] Write out a policy of what might be accepted/rejected
• [ ] Document Isso's internals
  • [ ] Python part:
    • [ ] DB structure
    • [x] Markdown rendering
    • [ ] Overview of libraries used
    • [ ] Document preferred coding style
    • [ ] Ensure references always mention python3 and pip3
  • [ ] Javascript part:
    • [ ] Overview of libraries used
    • [x] RequireJS vs CommonJS format, AMD (now using webpack)
    • [ ] What bundling/minification is
  • [x] Create an overview of all the tools/libraries/services associated with the project
  • [ ] Expand testing section to not only cover python part
  • [x] Testing with docker
  • [x] Pointing out easier ways to debug
  • [x] Once migration to webpack/pug/... is complete:
    • [ ] Explain internal structure of JS part and how to debug inside the browser console
    • [x] Document unit testing via jest
    • [x] Document e2e integration testing via puppeteer (and common errors)
    • [ ] Document preferred code style
• [ ] More purpose-oriented tagline (as opposed to "a disqus alternative")
• [ ] Theme:
  • [ ] Style external links (perhaps with :before and an outgoing link icon)
  • [ ] Mobile-friendly theme
• [ ] Add example cookie / GDPR policy (this necessitates explaining how Isso uses cookies and how long they're retained)

Related PRs

• https://github.com/posativ/isso/pull/848
• https://github.com/posativ/isso/pull/849
• https://github.com/posativ/isso/pull/833
• https://github.com/posativ/isso/pull/852
• https://github.com/posativ/isso/pull/853
• https://github.com/posativ/isso/pull/860
• https://github.com/posativ/isso/pull/867
• https://github.com/posativ/isso/pull/864
• https://github.com/posativ/isso/pull/863
• https://github.com/posativ/isso/pull/862
• https://github.com/posativ/isso/pull/876
• https://github.com/posativ/isso/pull/883
• https://github.com/posativ/isso/pull/875

[ix5]

Here's my take on an updated preview image (with slight borders), which is more real-life-like than the current preview at http://posativ.org/~tmp/isso-sample.png