EPIC: Documentation

[Baschdl]

• Code and usage documentation #41
• Design welcoming README page #33
• Add documentation for config-created database structures #80
• Document how we manage permissions in our project #60

[bjrne]

Why don't we create a milestone for this? :)

[Baschdl]

Would also be an option

[maltezacharias]

After initial discussion on documentation layout we wrote this, comments welcome! https://cryptpad.fr/pad/#/2/pad/edit/6-i8ZviQjknCCKwCBDlGTP9Z/

A few points to discuss, we think...

• the backend.dev.env should be included in the repo with working defaults, so you can quickly get started
• mail Backend & SMTP Configuration should be available through ENV Vars like everything else that likely needs to be changed
• dev should default to the file mail backend, because that's the only backend that reliably works everywhere for getting started
• similarly DEV-Settings should fallback to OSM when nothing else is configured

General Idea is to have:

• a github.io flashy page
• the rtd manual
• readme.md
• contributing.md

As documentation sources.

Another open question: It would be nice if we had 1-2 demo instances running somewhere, any ideas how/where to host those? @Baschdl @feeds @kevihiiin @josauder @maltezacharias @bjrne

[maltezacharias]

Also:

• Crossmatch with the documentatio requirements from DLR for the final summary report, maybe we can write things intentionally so, that they can be used for both
• We need your input for the cookbook section, should we do that? What should we include?

[Baschdl]

A Deploy to heroku button would be the easiest solution for us but not immediately usable without a heroku account

[Baschdl]

Everything sounds good.

We need your input for the cookbook section, should we do that?

From my perspective, "Cookbook > What do I need to do to ...." is the most important section

[kevihiiin]

Another open question: It would be nice if we had 1-2 demo instances running somewhere, any ideas how/where to host those?

@Baschdl I would love to have a "deploy to heorku button" There is procfile example in the Django-Cockie-Cutter respository on how to set it up (use Heroku's database server, rabbitmq, celery, etc).

What we also need for the demo instance is a way to display the mails that are sent (e.g. registration mails, found someone mail etc). We could use mailhog for that which mocks an smpt server and displays the recieved mails on a nice web interface.

[kevihiiin]

the backend.dev.env should be included in the repo with working defaults, so you can quickly get started

Providing a backend.dev.env.example like the .env.example which needs to be copied, but populate the .example with actual values? Or actually write values into the backend.dev.env, because then we cannot easily exclude real configuration files from git anymore

[Baschdl]

Or actually write values into the backend.dev.env

I would only do this for the heroku (or whatever) setup. I wouldn't do it in the repository because it's against good style to prevent security problems