Merge branch 'feature/2_docs_refactor' into develop

README.md

@@ -5,109 +5,60 @@
 
 [![Deploy to Docker Cloud](https://files.cloud.docker.com/images/deploy-to-dockercloud.svg)](https://cloud.docker.com/stack/deploy/)
 
-# Getting started
+ICEkit is a next-generation CMS by [the Interaction Consortium], built on top of
+[django-fluent-pages] and [django-fluent-contents]. See [ICEkit features at a
+glance](docs/intro/features.md)
 
-Create a new ICEkit project in the given directory (default: `icekit-project`):
 
-    $ bash <(curl -Ls https://raw.githubusercontent.com/ic-labs/django-icekit/master/icekit/bin/startproject.sh) [destination_dir]
+# Quickstart
+<!-- keep identical with docs/intro/install.md, except for link relativity. -->
 
-All other commands in this document should be run from the project directory.
+For detailed instructions, see [Manual Setup](docs/intro/manual-setup.md).
 
-NOTE: Windows users should run this command in Git Bash, which comes with
-[Git for Windows](https://git-for-windows.github.io/).
+## 1. Start a new project
 
-# Run with Docker
+With [Docker installed and running](docs/intro/docker.md),
+create a new project template with:
 
-The easiest way to run an ICEkit project is with Docker. It works on OS X,
-Linux, and Windows, takes care of all the project dependencies like the
-database and search engine, and makes deployment easy.
+    $ bash <(curl -Ls https://raw.githubusercontent.com/ic-labs/django-icekit/master/icekit/bin/startproject.sh) <project_name>
 
-If you haven't already, go install Docker:
+This script will create a new project in a directory named <project_name> in
+the current working directory, ready to hack on. NOTE: Windows users should
+run this command in Git Bash, which comes with
+[Git for Windows](https://git-for-windows.github.io/).
 
-  * [OS X](https://download.docker.com/mac/stable/Docker.dmg)
-  * [Linux](https://docs.docker.com/engine/installation/linux/)
-  * [Windows](https://download.docker.com/win/stable/InstallDocker.msi)
 
-Build an image and start the project:
+## 2. Run the project
 
+    $ cd <project_name>
     $ docker-compose build --pull
-    $ docker-compose up  # Watch for the admin account credentials that get created on first run
+    $ docker-compose up
+
+This will ensure all dependencies are installed and up to date, and will run
+a development server. <strong>Watch for the admin account credentials that get created on first run</strong>.</p>
 
-This will take a few minutes the first time. When you see the following
-message, you will know it is ready:
+It will take a few minutes the first time. When you see the following message, you will know it is ready:
 
     #
     # READY.
     #
 
-Now you can open the site in a browser:
-
-    http://icekit.lvh.me:8000  # *.lvh.me is a wildcard DNS that maps to 127.0.0.1
-
-Read our [Docker Quick Start](docs/docker-quick-start.md) guide for more info
-on running an ICEkit project with Docker.
-
-# Run without Docker
-
-Read our [Manual Setup](docs/manual-setup.md) guide for more info on running an
-ICEkit project without Docker.
-
-# Deploy to Docker Cloud
-
-Use the Deploy to Docker Cloud button above to create a new ICEkit stack on
-[Docker Cloud](https://cloud.docker.com/).
-
-You won't be able to [customise your project](#customise-your-project) when
-deploying the official ICEkit Docker image this way.
-
-# Configure your project
-
-You will need to provide some basic information to configure your project.
-
-You can do so with environment variables, or by editing the `docker-cloud.yml`
-and `icekit_settings.py` files.
-
-All settings are optional, but you can provide:
-
-  * `BASE_SETTINGS_MODULE` tells ICEkit to run in `develop` or `production`
-    mode.
-
-  * `EMAIL_HOST`, `EMAIL_HOST_PASSWORD` and `EMAIL_HOST_USER`, so ICEkit can
-    send emails (only in `production` mode).
-
-    We recommend [Mailgun](http://www.mailgun.com/), but any SMTP credentials
-    will do.
-
-  * `MASTER_PASSWORD` (only in `develop` mode) so you can login as any user
-    with the same password.
-
-  * `MEDIA_AWS_ACCESS_KEY_ID`, `MEDIA_AWS_SECRET_ACCESS_KEY` and
-    `MEDIA_AWS_STORAGE_BUCKET_NAME` so ICEkit can store file uploads
-    [Amazon S3](https://aws.amazon.com/s3/).
-
-    The specified bucket should already exist, or the credentials provided
-    should have permission to create buckets. This is especially important when
-    deploying to ephemeral infrastructure, like Docker Cloud.
-
-  * `PGDATABASE`, `PGHOST`, `PGPASSWORD`, `PGPORT` and `PGUSER`, if you need to
-    connect to provide credentials for your PostgreSQL database.
+## 3. That's it!
 
-    We recommend [Amazon RDS](https://aws.amazon.com/rds/), especially when
-    deploying to ephemeral infrastructure, like Docker Cloud.
+Open your new GLAMkit site in a browser:
 
-  * `SENTRY_DSN`, if you want to use [Sentry](https://getsentry.com/) for
-    real-time error tracking.
+    http://<project_name>.lvh.me:8000
 
-  * `SITE_DOMAIN` and `SITE_NAME`, so ICEkit knows how to generate redirects
-    correctly and knows what to call your site.
+(`*.lvh.me` is a wildcard DNS that maps to 127.0.0.1)
 
-# Customise your project
+# Next steps
 
-Anything you put in the `static` or `templates` directory will override the
-default ICEkit static files and templates.
+* Read the [overview of ICEkit architecture](docs/intro/architecture.md)
+* [Start building your site](docs/howto/start.md)
+* Read the [Documentation](http://icekit.readthedocs.io) on Read the Docs
 
-You can specify additional Bower components in `bower.json`, Node modules in
-`package.json`, and Python packages in `requirements.txt`.
+<!-- editors guide -->
 
-The `icekit_settings.py` file is a Django settings module. You can override any
-default ICEkit settings or configure apps installed via `requirements.txt`.
+[django-fluent-contents]: https://github.com/edoburu/django-fluent-contents
+[django-fluent-pages]: https://github.com/edoburu/django-fluent-pages
+[the Interaction Consortium]: http://interaction.net.au

docs/changelog.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## Develop
+
+  * Refactor docs to provide better onboarding.
+
 ## 0.11 (29 August 2016)
 
   * Serve Django with Nginx/Gunicorn under Supervisord, to buffer requests,
@@ -56,9 +60,9 @@ New:
 
 Backwards incompatible changes:
 
-  * Make content plugins [portable](portable-apps.md). You will need to run an
-    SQL statement for each plugin manually to fix Django's migration history
-    when upgrading an existing project.
+  * Make content plugins [portable](topics/portable-apps.md). You will need to
+  run an SQL statement for each plugin manually to fix Django's migration
+  history when upgrading an existing project.
 
         UPDATE django_migrations SET app='icekit_plugins_brightcove' WHERE app='brightcove';
         UPDATE django_migrations SET app='icekit_plugins_child_pages' WHERE app='child_pages';

docs/contributing/conduct.md

@@ -0,0 +1,71 @@
+# Code of conduct
+
+We have a few ground rules that we ask people to adhere to. This code applies
+ equally to founders, mentors and those seeking help and guidance.
+
+This isn’t an exhaustive list of things that you can’t do. Rather, take it in
+the spirit in which it’s intended - a guide to make it easier to enrich all
+ of us and the technical communities in which we participate.
+
+This code of conduct applies to all public spaces managed by the Interaction
+Consortium (IC). This includes chat rooms, the mailing lists, the issue
+tracker, IC events, and any other forums created by the project team
+which the community uses for communication. In addition, violations of
+this code outside these spaces may affect a person's ability to participate
+within them.
+
+If you believe someone is violating the code of conduct, we ask that you
+ report it by emailing labs@interaction.net.au.
+
+* **Be friendly and patient.**
+* **Be welcoming.** We strive to be a community that welcomes and supports people
+of all backgrounds and identities. This includes, but is not limited to
+members of any race, ethnicity, culture, national origin, colour,
+immigration status, social and economic class, educational level, sex,
+sexual orientation, gender identity and expression, age, size, family
+status, political belief, religion, and mental and physical ability.
+* **Be considerate.** Your work will be used by other people, and you in turn will
+depend on the work of others. Any decision you take will affect users and
+colleagues, and you should take those consequences into account when making
+decisions. Remember that we're a world-wide community, so you might not be
+communicating in someone else's primary language.
+* **Be respectful.** Not all of us will agree all the time, but disagreement is no
+excuse for poor behavior and poor manners. We might all experience some
+frustration now and then, but we cannot allow that frustration to turn into
+a personal attack. It’s important to remember that a community where people
+feel uncomfortable or threatened is not a productive one. Members of the
+Django community should be respectful when dealing with other members as
+well as with people outside the Django community.
+* **Be careful in the words that you choose.** We are a community of
+professionals, and we conduct ourselves professionally. Be kind to others.
+Do not insult or put down other participants. Harassment and other
+exclusionary behavior aren't acceptable. This includes, but is not limited to:
+    * Violent threats or language directed against another person.
+    * Discriminatory jokes and language.
+    * Posting sexually explicit or violent material.
+    * Posting (or threatening to post) other people's personally identifying
+    information ("doxing").
+    * Personal insults, especially those using racist or sexist terms.
+    * Unwelcome sexual attention.
+    * Advocating for, or encouraging, any of the above behavior.
+    * Repeated harassment of others. In general, if someone asks you to stop, then
+     stop.
+* **When we disagree, try to understand why.** Disagreements, both social and
+technical, happen all the time and Django is no exception. It is important
+that we resolve disagreements and differing views constructively. Remember
+that we’re different. The strength of Django comes from its varied
+community, people from a wide range of backgrounds. Different people have
+different perspectives on issues. Being unable to understand why someone
+holds a viewpoint doesn’t mean that they’re wrong. Don’t forget that it is
+human to err and blaming each other doesn’t get us anywhere. Instead, focus
+on helping to resolve issues and learning from mistakes.
+
+Original text courtesy of the [Django Code of Conduct], which in turn credits
+the [Speak Up! project].
+
+[Django Code of Conduct]: https://www.djangoproject.com/conduct/
+[Speak Up! project]: http://speakup.io/coc.html
+
+## Questions?
+
+If you have questions, please feel free to [contact us](mailto:labs@interaction.net.au).

docs/contributing.md → docs/contributing/contributing.md

@@ -62,6 +62,7 @@ Docs are probably more important than tests!
   * Keep the [changelog] up to date. Use plain language to describe changes,
     as it may be read by people who are not familiar with the project or a
     particular feature.
+  * Document all functions that don't begin with an underscore.
 
 ### HTML Docs
 
@@ -84,7 +85,7 @@ We don't need 100% test coverage, but we should at least have:
   * When the changelog for a release gets sufficiently long or major features
     or fixes are implemented, tag a release.
 
-[changelog]: changelog.md
+[changelog]: ../changelog.md
 [EditorConfig]: http://editorconfig.org/
 [git-extensions]: https://github.com/nvie/gitflow/
 [Gitflow]: http://nvie.com/posts/a-successful-git-branching-model/

docs/contributing/roadmap.md

@@ -0,0 +1,3 @@
+# Roadmap
+
+To follow. For enquiries, write to labs@interaction.net.au.