Heads up everyone, those obsolete, dusty things you never look at are coming back into fashion in the Ubuntu world!
Manual fever is gripping Ubuntu community teams all over the world as everyone starts to copy the Ubuntu Manual Team’s fairly obvious choice of sticking content inside a PDF and producing it as a book.
The Ubuntu Developers Manual
The opportunistic developer initiative, driven by Rick Spencer and Jono Bacon, had a session at UDS to talk about a “Developers Manual” that would cover all the tools you need to start programming in Ubuntu and developing applications using Quickly, Launchpad, Ground Control, Glade etc. The session also proposed using a consistent example python application and building on it for each chapter, adding new features and hence teaching the reader how to write decent applications for Ubuntu in an expedited fashion.
The Getting Started with Translations Guide
The translation coordinators have decided that the current instructions for helping new translators are too complicated and that their wiki contains hyperlinks that link to a list of hyperlinks. It’s link central. In the Maverick cycle, there will be work on simplifying the landing page for the translator documentation and help, and also to record some screencasts to show new translators how to use Launchpad. Of course, no surprise here, the new content will be packaged as a manual and available as a PDF guide.
LoCo Team Manual
While not confirmed, there was talk of a LoCo team manual that would discuss ways that people can set up a new LoCo team and provide hints on collaborating with other teams, the events throughout the year like Global Bug Jam and Ubuntu Open Week, and also giving some information on how to host successful physical LoCo team events.
Packaging Manual
Just like above, this would focus on producing a document that helps new people with packaging, how they can contribute to the packaging and who they would need to contact to learn more.
So what’s so special about manuals?
- Location – everything is in one place, in one PDF file, not spread out over the internet or buried in piles of wiki pages
- Consistency – by working collaboratively on a document, you can easily see the work that other people have done previously, establish a style guide and use a markup language that allows consistent formatting across the entire document
- Distribution – people can download and view PDFs on most operating systems and mobile devices, embed them in a website, purchase them from Lulu.com or print them at home
- Visual aids – embed things like margin notes, screenshots and diagrams in the right place and in the same place to break up text and offer some visual way of getting your point across
- Contextualized and Linear – design the manual like a book with a shallow learning curve, people can read from start to finish and go from not even knowing anything about the project to being an expert in that area by the time they’re finished
- Version control – create a PDF for each release of Ubuntu and follow the same release schedule, if someone wants to know information on a particular version of Ubuntu, they just have to download the correct PDF
- Sharing offline – slam it on a USB stick or a Kindle and give it to your friends, use it to troubleshoot a broken system or just to read when you’re on the shitter
- Translations – using a markup language like TeX and working with po4a, a PDF manual can be translatable using Launchpad and therefore able to be distributed locally, and to more people.
Of course, PDF manuals aren’t the answer to all the world’s problems. They’re not going to solve the gigantic oil spill in the Gulf of Mexico, the Greek economy falling to pieces or Justin Bieber, but the important thing to realize is that once you have the content in place and the first format, you can then look at producing more formats to further keep everyone happy and get your material out to everyone on the face of the Earth.