Ubuntu Accomplishment Editor Spec
Problem and Opportunity
One of the core values of the Ubuntu Accomplishments system is that you can find comprehensive guidance and information about how to achieve the different trophies and learn the skills involved in their aquisition. To do this there is built-in documentation that looks like this:
For us to have great documentation in these accomplishments we need to ensure our wider documentation community are able to contribute. Unfortunately today, while not hugely complicated, contributing is a little more complex than it needs to be. It involves:
Branching lp:ubuntu-community-accomplishments (or any other accomplishments set).
Editing the documentation in the accomplishments/ directory, making sure to adhere to the accomplishment documentation specification.
- Commit these changes to Bazaar and push them to Launchpad.
- Request a merge proposal to have your changes included in the accomplishments set.
The goal is to create a web app that provides a simple interface to contributing documentation.
I have started work on this in lp:~jonobacon/ubuntu-accomplishments-system/accomplishments-web-editor. It is written using Django.
Here is how you use it:
First ensure you have the accomplishments installed in the accomplishments dir in your home directory. See https://wiki.ubuntu.com/Accomplishments/Installing for details of how to install the system.
Now grab the branch:
bzr branch lp:~jonobacon/ubuntu-accomplishments-system/accomplishments-web-editor
Inside the branch to the README file for how to get set up.
Nothing here is cast in stone, but this is a system that I think could work well; comments and suggestions are welcome. Please discuss them on the mailing list.
The system would work like this:
Login would be handled by the Ubuntu SSO service, oh which we have support for Django applications.
Admins - admins run the site and perform the following functions:
- import new branches of accomplishments to be supported by the site.
- publish approved contributions.
Moderators - moderators can review contributions and accept them into accomplishments sets as well as making their own contributions directly.
Contributors - contributors are able to suggest improvements to accomplishments.
Any visitor to the site would be a contributor and a certain accounts would be moderators and admins.
When a user visits the site they can see a list of all available accomplishments across the different accomplishments sets that the system knows about:
We may also want to include other ways of filtering these accomplishments so users can find things of interest to them, or even a way of identifying which accomplishments need the most attention in terms of docs.
When the user clicks on an accomplishment they are taken to the editing view...
Editing an Accomplishment
This page provides a form that is pre-populated with all the content from the accomplishment (please note: this mock-up does not include all fields in the form due to space limitations...we would instead show more fields):
The user can then edit the content and add and improve documentation for the accomplishment. When the user submits the form, it gets added to the contributions queue...
Viewing the Contributions Queue
This queue would only be visible to admins and moderators on the site. The queue provides a list of contributions that need to be reviewed:
Here the accomplishment that was edited is shown and the name of the contributor is shown in brackets (we can get their name or username from Ubuntu SSO).
Again, we could explore other ways of filtering and viewing this content, but the mock-up above gives you the general gist of how it would work.
Clicking on an item allows the admin or moderator to review the item...
Reviewing a Contribution
Here we can see the contribution. We will need to show some kind of diff showing what changed from the accomplishment and the changes made by the contributor. This may be possible by showing it inline, or using the more traditional view of showing diffs (such as the one shown in Launchpad). Fortunately difflib in Python should make this simple (it even includes a HTML output for diffs).
It looks like this:
Here the admin or moderator can review the contribution and choose one of three options:
- Approve - if the contribution looks good, it can be approved. More on what happens when it is approved below.
- Defer - if the admin/moderator can't decide or wishes to provide feedback to the contributor, they can use this open and the text box below to add a message.
- Reject - if the contribution is not acceptable, they can use this option and add a message to the text box below.
Finally, if the admin/moderator wishes to make a change to the contribution (e.g. to make one small change and then approve, they can the Edit View to toggle the view in a form mode.
As mentioned above, there is an implementation of this started at lp:~jonobacon/ubuntu-accomplishments-system/accomplishments-web-editor. Here are some notes for how some of this could be implemented.
We should be able to use Ubuntu SSO for this - there is an Ubuntu SSO module.
Importing Accomplishments Sets
The system should support multiple accomplishments sets (e.g. lp:ubuntu-community-accomplishments is one set). Each set of accomplishments is just a collection of ConfigParser .ini files so these are easy to read into a database; the draft implementation already does this.
We should problably make this an option only available to admins: an admin click a button on an admin interface to read in a set of accomplishments.
In the draft implementation there is a database table for the accomplishments from the set that are read in, and then another table for AccomplishmentDiff that contains the differences. This makes it easy to show a diff using difflib in the queue review view.
When a contribution is approved by an admin or moderator, the following occurs:
- The .accomplishment file in the branch is updated with the new documentation.
- The file is committed to the branch.
The branch is then pushed to it's Launchpad branch (e.g. lp:ubuntu-community-accomplishments)
This way there is no handling of commits and pushes, and we have a user-friendly interface for our contributors.
A core goal for the Web Editor is to support the editing of translated accomplishments. Please note: when we say translations here are only referring to the translations of the accomplishments files (as this is all the web editor is interested in) and not the translation of the GUI client app (that is a seperate project).
Currently the Ubuntu Accomplishments system does not provide any support for accomplishments in multiple languages. I would like to propose a format for how this will work for a typical accomplishments set, and we can then discuss the Django implementation for the Web Editor.
Accomplishment Set Translations
Every accomplishments set has accomplishments and scripts sub-directories. We only care about translations in the accomplishments directory (the .accomplishment files).
Currently the director looks like this:
ubuntu-accomplishments/ accomplishments/ first-bug.accomplishment signed-code-of-conduct.accomplishment . . .
My idea here is to add each translated set in it's own language specific sub-dir:
ubuntu-accomplishments/ accomplishments/ en_gb/ first-bug.accomplishment signed-code-of-conduct.accomplishment . . . fr/ first-bug.accomplishment signed-code-of-conduct.accomplishment . . . de/ first-bug.accomplishment signed-code-of-conduct.accomplishment . . .
This way the client application will load the appropriate set after detecting the local locale on the machine.
Django Web Editor Translations
If we adopt the above approach for translations of accomplishments files this means that we can map this to Django reasonably easy.
I want to document some ideas for how the user experience could work and then we can discuss the data model implementation.
The user experience could work like this:
- The user visits the web editor and is able to select a set of language(s) that they know.
- The list of accomplishments is displayed for each accomplishments set (as it is in the current web editor) and a flag or string is next to each one indicating which language you can edit the accomplishment in
- If the user clicks the flag (e.g. French flag) or string (e.g. "French") it takes them to a screen which looks like the current accomplishments edit form but displays the English translation on the left and the chosen language on the right with edit boxes.
I (Jono) am not the best person to model the data structure due to my lack of experience with serious Django work, but some initial thoughts:
When a user chooses an accomplishment and make an edit it saves the diff in a different table if I remember right (AccomplismentProposal?). This proposal should probably also store the language that the proposed change is for.
When a proposal is accepted it should be saved in the above file structure (e.g. a 'fr' translation would be stored in accomplishments/ubuntu-community/fr/<foo>.accomplisments).