Merge pull request #19 from degville/readme-updates

Readme updates

Author: degville

README.md

@@ -1,31 +1,119 @@
 # Open Documentation Academy
 
-The Open Documentation Academy combines Canonical’s documentation team with documentation newcomers, experts, and those in-between, to help us all improve documentation practice and become better writers.
+*Discover open source through documentation*
+
+The Open Documentation Academy combines Canonical’s documentation team with documentation newcomers, experts, and those in-between, to help us all improve documentation practice and become better writers. Fill blanks in your resume and paint your GitHub activity tracker golden.
 
 If you're a newcomer, we can provide help, advice, mentorship, and a hundred different tasks to get started on. If you're an expert, we want to create a place to share knowledge, a place to get involved with new developments, and somewhere you can ask for help on your own projects.
 
-A key aim of this initiative is to help lower the barrier into successful open-source software contribution, by making documentation into the gateway. 
+A key aim of this initiative is to help lower the barrier into successful open-source software contribution, by making documentation into the gateway.
+
+[Join the academy HERE](https://discourse.ubuntu.com/c/open-documentation-academy/166)
 
-## What you’ll get out of it
+## This repository
 
-**Real experience, real skills, real discipline**: Open-source products in the Canonical/Ubuntu industry are highly-respected and used by millions of people. Standards for contributions are high. You’ll have a chance to contribute to prestigious projects, and acquire the skills to take part in the development of world-class software.
+The purpose of this repository is to list and track global documentation tasks. These are filed as _issues_ in this repository. Tasks vary from broken formatting and missing documentation, to updates, re-structuring, and rewriting.
 
-**Structured support**: The Open Documentation Academy will include a structured programme of support and development for serious participants, taking them from their first steps to having the confidence to lead their own documentation initiatives.
+Issues are identified and shared by participating projects at Canonical who control whether an issue is merged into their documentation. An academy participant and a mentor work together to guide a contribution through to completion.
 
-**Recognition**: Your contributions will speak for themselves, but we’ll vouch for you too. Participants who complete our programme will receive certification from Canonical.
+### Participating projects
 
-## What we offer
+The first words of an issue's title will typically indicate the project it involved. These include the following:
 
-**Mentoring**: You are not alone. Regardless of whether you're writing your first document, or editing your hundredth, we're here to help. Our 1:1 mentorship can help you through your first contributions, provide advice on approaches, and help you build your confidence.
+- [Canonical OpenStack](https://ubuntu.com/openstack/docs): our enterprise cloud platform 
+- [Juju](https://juju.is/docs):  open source orchestration engine
+- [Canonical Kubernetes](https://ubuntu.com/kubernetes/docs): the reference platform for Kubernetes on all major public clouds
+- [LXD](https://documentation.ubuntu.com/lxd/en/latest/): open source container and VM management at any scale
+- [Launchpad](https://documentation.ubuntu.com/launchpad/en/latest/): software development lifecycle and collaboration platform
+- [MAAS](https://maas.io/docs): bare metal cloud with on-demand servers
+- [Our Sphinx and RST starter pack](https://github.com/canonical/sphinx-docs-starter-pack): our open source template for building modern documentation
+- [Snap and Snapcraft](https://snapcraft.io/docs): Linux app packages and the build tools for desktop, cloud and IoT
 
-**Guided contributions**: Help us identify gaps, nominate solutions, and propose documentation of your own. We curate tasks across a variety of different open source projects. Choose a task you're interested in, at a level you're comfortable with, and make a contribution. Research. Write. Commit. Fill blanks in your resume and colour your GitHub Activity tracker golden.
+This list will expand as more projects get involved. We're also happy to include projects outside of Canonical.
 
-**Community**: Through our forum and communication channels, you can directly interact with documentation teams and co-conspirators across the globe. We want our community to be friendly, inclusive and always supremely approachable, in accordance with the Ubuntu Code of Conduct.
+### Issue labels
 
-## This repository
+We use one or more of the following issue labels both for consistency and to indicate what might be expected from a task.
 
-The purpose of this repository is to list and track global documentation issues for the Academy. Issues vary from broken formatting and missing documentation, to updates, re-structuring, and rewriting.
+#### diátaxis
 
-Issues are identified and shared by participating projects at Canonical who control whether an issue is merged into their documentation. An academy participant and a mentor work together to guide a contribution through to completion.
+Revise a document to better conform to a [Diátaxis](https://diataxis.fr/) type:
+
+- Tutorial
+- How-to
+- Reference
+- Explanation
+
+This may require a document to be split, edited, or sometimes re-written.
+
+#### edit
+
+Edit pre-existing documentation for consistency, accuracy, style and application.
+
+#### explanation
+
+Create or revise a document to better reflect an understanding-oriented [explanation](https://diataxis.fr/explanation/).
+
+#### good first issue
+
+An ideal task to start with. Marking issues with this label is a widely adopted [GitHub convention](https://github.com/topics/good-first-issue).
+
+#### help wanted
+
+Another [GitHub convention](https://github.com/topics/help-wanted) to indicate that a project welcomes community help with an issue. 
+
+#### how-to
+
+Create or revise a document to better reflect a [how-to guide](https://diataxis.fr/how-to-guides/) to achieve a specific goal.
+
+#### new
+
+Adding new or missing documentation for a specific tool, feature, or function.
+
+#### oda-admin
+
+Tasks relating to the admin of the Open Documentation Academy (ODA) project.
+
+#### reference
+
+Create or revise a document to better reflect a technical description to use as [reference](https://diataxis.fr/reference/) material.
+
+#### review
+
+Review pre-existing documentation for quality, accuracy and consistency. This work may require small updates to the original documentation and/or the creation of sub-tasks to address any detected and substantial shortcomings.
+
+#### size 
+
+This is our estimation of effort and complexity. Size values range from 1 to 8, representing _least effort_ to _most effort_ respectively. These numbers follow the [Fibonacci ### sequence](https://en.wikipedia.org/wiki/Fibonacci_sequence) sequence of 1, 2, 3, 5, 8, with size 8 likely to be a significant undertaking.
+
+#### tutorial
+
+Develop, write, edit or update a [tutorial](https://diataxis.fr/tutorials/). Tutorials are often the hardest kinds of documentation to write or update because they primarily require good teaching skills and perception, before you even start writing.
+
+#### update
+
+Update potentially outdated instructions, commands, or version numbers. These tasks might include release notes, version numbers, new command line arguments and features, and even complete overhauls when a major release occurs.
+
+## Further resources
+
+### Community forum
+
+Our community forum is the hub for all things Open Documentation Academy. It includes our _Getting started_ guide and links to our weekly _Documentation office hours_, alongside  meeting notes, updates, external links and discussions.
+
+<https://discourse.ubuntu.com/c/open-documentation-academy>
+
+### Synchronous chat
+
+For more interactive chat, the documentation team can be found on [Matrix](https://matrix.org/).
+
+<https://matrix.to/#/#documentation:ubuntu.com>
+
+### Social media
+
+You can find us on [Fosstodon](https://fosstodon.org/explore), where we post frequent updates related to the _Academy_ and our other documentation initiatives.
+
+<https://fosstodon.org/@CanonicalDocumentation>
+
+### Calendar
 
-For more information, or to get involved, visit [https://canonical.com/documentation](https://canonical.com/documentation).
+Subscribe to our [Documentation event calendar](https://calendar.google.com/calendar/u/0?cid=Y19mYTY4YzE5YWEwY2Y4YWE1ZWNkNzMyNjZmNmM0ZDllOTRhNTIwNTNjODc1ZjM2ZmQ3Y2MwNTQ0MzliOTIzZjMzQGdyb3VwLmNhbGVuZGFyLmdvb2dsZS5jb20). Not only does this include our _Documentation office hours_, it will also include any other discussion or training events we organise.