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)

• Expand README, which serves as first point of contact for many people new to Isso
• Expand FAQ
• 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)
• Overhaul contributing section
  • Point out more ways to contribute
  • Link to "contributor-needed" label
  • Write out a policy of what might be accepted/rejected
• Document Isso's internals
  • Python part:
    • DB structure
    • Markdown rendering
    • Overview of libraries used
    • Document preferred coding style
    • Ensure references always mention python3 and pip3
  • Javascript part:
    • Overview of libraries used
    • RequireJS vs CommonJS format, AMD (now using webpack)
    • What bundling/minification is
  • Create an overview of all the tools/libraries/services associated with the project
• Expand testing section to not only cover python part
  • Testing with docker
  • Pointing out easier ways to debug
  • Once migration to webpack/pug/... is complete:
    • Explain internal structure of JS part and how to debug inside the browser console
    • Document unit testing via jest
    • 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

• [docs] [MAJOR] Re-arrange, add a few missing pages to be filled in #848
• [docs] Improve apiDoc handling, add entry to Makefile, flourish #849
• [docs] Add "Edit on GH" links, fix searchbox, widen viewport, better legibility #833
• docs [MAJOR]: Fill in community, testing, contrib pages, add news entries  #852
• docs: contrib: More links, explain building the docs, syntax #853
• docs: Expand community & Writing docs pages, import wiki articles #860
• README: Include more information, new screenshot #867
• [docs] Add Markdown rendering explanation, refs, more styling of tables and other elements #864
• [docs] Reduce width; code highlighting changes, installation guide improvements, prompt blocks #863
• docs: Document snapshots, add "New in version x", def.-list styling, better config options documentation #862
• [docs] Document server testing/pytest a little more clearly #876
• [server] Remove obsolete /count GET, apiDoc improvements #883
• WIP: [docs] Expand releasing section #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