What?

The DocumentationTeam is thinking about ways to obtain good feedback from users about what subjects should be dealt with in the documents, and also to involve the wider community more in the document writing process.

For this reason, we are considering holding a competition of sorts where any Ubuntu user can send in snippets for inclusion into our docs. If such a submission is accepted, the user would get credit within the document's credits section. We will also think about other prizes.

After the competition finishes the system will stay in place as a feedback system, the aim of the competition is to highlight the use of it.

Documents Involved

• All

Running The Competition

The competition should be announced as widely as possible, on such places as the Fridge, the forums and IRC. We should also announce it on our home page, doc.ubuntu.com and we should make it clear that not "all" submissions will be accepted, and the submitter will only receive credit if the suggestion is accepted. It would be up to the maintainer to sought through the list of submissions, and if the docteam as a whole wishes to be involved submissions can be discussed at a docteam meeting.

There is a couple of options we could use to accept submissions, perhaps the easiest way for people to submit is via a web page where we could ask for their name, and suggest the proper layout. Other possibilities include the docteam mailing list, or to another email address.

Implementation

Since the system would be designed as a permanent feedback system, with the competition to give it some initial impetus, we should implement a decent long-term feedback infrastructure. There are the following possibilities:

• Web form - we'd have to write one, including a way of viewing whats been submitted.
• Wiki page - barrier to participation, as some users will lose interest before registering and logging into the wiki (especially true for forum users that have a separate registration there already)
• Mailing list - barrier to participation, as you need to sign up. Also, overkill as every person signed up to the list will get a copy, if the scheme is successful this would be too high volume.
• A feedback-only mailing list (eg docteam-feedback) - authors could subscribe to such a list and filter it from their normal email.

Format of Submissions

We also need to give some thought to how users can submit the feedback. There are two types of submissions which we can encourage:

1. We should encourage them to give actual submissions which are ready for the documents. For example, a suggestion for the DesktopGuide might be:

   Q: How to fix a leaking tap:
   A: Buy a new washer for the tap.

   • Some re-wording of submissions may be required to fall in line with the Style Guide, however the above format is easily put into Docbook XML and included within the document.

2. However we should also encourage users simply to submit "requests" on what subjects they would like to see answers for in the docs, without necessarily submitting those answers themselves.

We should also define categories for which we want suggestions so that entries are within the scope of the document. These could follow the outlines in the specs for the pages (e.g. see DesktopGuide)

Prizes

• Credit within the document is the obvious one.
• Other prizes?
  • Ubuntu t-shirts/stickers etc?

Suggestions?

How about building a feedback process at multiple levels in the existing documentation bundled with Ubuntu? For example, having a universal, overarching keyword search for help topics would be great (a la OS X), with a link at the bottom of the results to the effect: "Want to see more documentation here?"

Use case: User searches for help on topic X. Can't find what she needs, so she clicks on the link to add more documentation. Is taken to an offline (machine-resident) form that asks her to fill out basic information on what she was looking for, and outlines the benefits of contributing her own documentation or ideas, and offers a link to another form in case she wishes to do so. Otherwise, the form information is saved, and either transmitted back to Ubuntu or transmitted the next time the machine is connected to the internet. 

Thoughts?

Dave Chakrabarti. 

• Yeah this is along the lines of what I was thinking, although I was thinking perhaps even simpler: a link in the header of each help page (at least in the online version) which invites the user to submit feedback if they didn't find something, and takes them to a simple webform, which asks them which guide they were looking in, and which section etc. As for search, I'm not sure we need it: the guides should be so self-evident (even for new users) that it is obvious where to find everything. Each guide should not overlap with others. This is a big part of where I want the documentation to go for dapper. As for the documents in the distribution itself, Yelp doesn't support search yet, I don't think. Not sure if we can add a comment link to each page, but we can investigate! Thanks for your feedback! (mdke)