Here are some comments from one of the Ubuntu Documentation team members, that I thought everyone should read. He has some valid points.
------------ Hi Benjamin, Thanks for answering those questions. I've provided some thoughts/advice based on my experience, below. I hope you find them useful. TARGET AUDIENCE It's extremely important to have a very good idea of who your target audience are. The problem with writing documentation is that it's very easy to write something that you understand, but it's not so easy to write something that other people will understand. Try (verbally) explaining a concept like "hardware drivers" to someone who is not technically inclined, and you'll see what I mean. You need to figure out who your readers are, what they know, and what they are trying to achieve (i.e. why they are reading your document). That way, you can make sure that you are adequately catering for their needs. The most common way of doing this is to develop a few personas [1] which represent your users. The doc team can offer lots of help with this, if you like. In the FAQ, you say that the level of technical ability ranges from newbie to someone who is familiar with Windows. Be very careful with this; we've found in the past that writing for experienced and inexperienced people at the same time can lead to docs which aren't useful to either group. Inexperienced users need lots of things to be explained and jargon to be avoided. Experienced users don't care about most of this, and are just looking for specific information, such as a command. The experienced user will then find that the information which is interesting to them is buried in a load of irrelevant stuff, which makes the document difficult for them to read. This was what my question 6 was about; you can't satisfy everyone. MAINTENANCE Writing a document is lots of fun, and it's typically not too difficult to get people involved. However, once the document is written and you need to maintain it, the task becomes much more boring. This is something that the Doc Team struggles with; only a few people are interested in keeping documents up-to-date. Maintenance involves reading, checking and modifying the whole document, every six months in our case. This can be very tedious, especially if major changes have been made over that release cycle. Maintenance is more difficult than writing because writing allows you to exercise some creativity; when performing maintenance editing, you are constrained by the material that is already written. It's also good to think about what happens if *you* lose interest in the guide. Who will maintain it then? TRANSLATIONS I saw that you'd chosen to write the document in LaTeX. I'm not sure what translation infrastructure exists for LaTeX, or whether it's compatible with Launchpad's Rosetta system. You should also be aware that translators need lots of time to work on a document, especially if it's 50 pages, and that screenshots can be difficult for translators to handle. LICENSING Please don't use the GPL! It makes remixing and reuse pretty much impossible, and I think it requires you to track versions in an awkward way. CC-BY-SA is the license the Doc Team recommends. CHOOSING TOPICS I see that you're choosing topics based on forum threads and existing community docs. This will seriously bias your choice of topics, since you'll only be picking up suggestions from people who are interested enough in Ubuntu to be reading the forums on a regular basis. These people are likely to have a higher level of technical skill than average, so you'll get suggestions which are too technical for most people, and you'll miss lots of issues which novices really struggle with. You'll probably end up with a section on configuring compiz or fluxbox, and miss out the section on "Where are my programs?" if you just use suggestions from the forums! A good way of choosing topics is to find people who match your user personas and then watch them trying to use Ubuntu (without prompting them or telling them what to do when they get stuck). This can be very revealing - you'd be amazed by what people get stuck with. Afterwards, you can interview the person too. It's hard work, but ultimately worth it. Thanks, and good luck with the project ----------- -- Benjamin Humphrey [email protected] www.interesting.co.nz www.benjaminhumphreyphotography.com _______________________________________________ Mailing list: https://launchpad.net/~ubuntu-manual Post to : [email protected] Unsubscribe : https://launchpad.net/~ubuntu-manual More help : https://help.launchpad.net/ListHelp
