Make the localconfig.template.yml explain what rather than how

[limikael]

I think that the localconfig.template.yml file has... well... a bit too much documentation...

Maybe we can cut it down for example the PROFILE section to something like this, also describing the options of what the user is likely to want to do:

#### PROFILE ####
# A profile defines collections of server roles that are frequently 
# installed together. Uncomment the one you need.
# For implementation details, see <reference to more detailed doc>.

# Development environment for the swag system.
# profile: swag_dev

# A typical classroom server.
# profile: classroom_server

[usernamenumber]

I'll need to write up that reference doc first (or if you or anyone else wants to try writing a draft as a way to learn how everything works...), but once that's done, I agree with making this change.

[usernamenumber]

Another change I want to make: instead of profile:, have profiles:, and have it accept a list of values that are evaluated as:

if playbooks/$NAME.yml exists:
  include that playbook
elif playbooks/roles/$NAME exists:
  include that role
else:
  zomgerrorz

That way if you were deploying something fancy that already has its own playbook, like swag_dev, but wanted to add the webmail system to it, you would just run put something like this...

profiles:
  - swag_dev
  - webmail

and provision.py would create and run a playbook like this:

---
- include: common/starting_stuff.yml
- include: profiles/swag_dev.yml # I'm considering profiles to their own dir
- hosts: all
  roles:
    - webmail
- include: common/ending_stuff.yml

Mentioning this partly as a note to myself, partly in case someone has comments, and partly so you don't want to kill me if you do write a draft and then I change things unexpectedly. :P

[limikael]

Where should the reference documentation be?

I can maybe put things there as I encounter problems and find ways to fix them (if I find ways to fix the problems I encounter, that is).

Can't say that it will be comprehensive from the start though, but good to get it started...

[usernamenumber]

I'd say put it in the wiki (new doc, not the setup doc), and just include "DRAFT" in the title so people know not to treat it as authoritative yet.