Ubuntu: A Beginners Guide

[Kyle Nitzsche]

Hi Benjamin,

Instead of OpenOffice as the source format, you might consider 
single-sourced docbook. When set up properly this allows:

 * true single sourcing (content is never duplicated, even for translations)
 * easy localization (translations and images - for example screenshots)
 * conversion to multiple localized output formats (html, pdf, docbook) 
with a single command

There's a project that makes all this easy: 
http://launchpad.net/doctemplate.

That project has a PPA that allows you to install the doctemplate 
package:  https://edge.launchpad.net/~doctemplate-team/+archive/ppa
Just add that to your System > Administration > Software Sources then 
install doctemplate with:
 * "sudo apt-get update"
 * "sudo apt-get install doctemplate"

Once doctemplate is installed:
 * you create a new docbook article or book in the current directory 
with a single command ("doctemplate_setup_article" or 
"doctemplate_setup_book")
 * docbook content that is ready to edit, modify and build is created
 * you generate localized pdf, html, docbook, with a single command 
("make_pdf" "make_html" "make_docbook")
 * translations are in po files that can be updated from source with a 
single command, and localized outputs always use the po files. po files 
can be translated in Launchpad or using many other  available  
tools/websites.

The guiding design/development principle for doctemplate is: make it 
easy for writers to write by handling the techy bits.

Docbook does have a handful of tags the writer needs to know. They are 
well-documented on the web, for example: 
http://www.docbook.org/tdg/en/html/article.html.

You can edit the docbook files in various applications, including text 
editors like gedit. The bluefish package provides some pretty good 
docbook specific functions.

I am currently finalizing the short documentation for doctemplate: 
https://edge.launchpad.net/doctemplate-user-guide

Get the docs this way:
(you have to have the "bzr" package installed.)

'bzr branch lp:doctemplate-user-guide"

Then, in the root directory, run "./make_html"

Then display the English version with: "firefox build/html/en/index.html"

(or, to make a pdf, run "./make_pdf" and display it with "evince 
build/pdf/en/doctemplate-doc.pdf".)

(or to make localized docbook, run "./make_docbook" and display it in 
yelp with "yelp build/xml/en/doctemplate-doc.xml")

(The doctemplate-user-guide is also written using the doctemplate approach.)
 
Cheers,
Kyle





Benjamin Humphrey wrote:
> Hello everyone,
>
> Recently I started up a project to write a manual for Ubuntu that is 
> both informative and easy to follow. My goal is around 50-75 pages, 
> and perhaps having two different versions - one in-depth guide that 
> covers pretty much everything, and one 10 page Quick Start guide, 
> which, in the future, could be shipped with the Ubuntu CDs.
>
> I began writing it myself, but after deliberation and advice from 
> other users, it would be better to make it a community effort. The 
> idea is to have the first release ready for Lucid, and then a refresh 
> every 6 months to coincide with a new Ubuntu version. Eventually, I 
> hope it becomes the first point of reference for any Ubuntu newcomers.
>
> We need contributors, and I thought the best place to start would be 
> the documentation team.
>
> I was talking with Jono Bacon tonight and he suggested the ideal way 
> to go about testing/feedback/contributions for the manual is via 
> Launchpad. He is really excited about the idea and is interested to 
> see how it pans out – so am I.
>
> Therefore, I’ve just created a Launchpad team for the Beginners Manual:
>
> https://launchpad.net/~ubuntu-manual 
> <https://launchpad.net/%7Eubuntu-manual>
>
> I’ll set up a bzr tomorrow and upload the .odt and .pdf of what I have 
> so far (about 3 rough chapters), feel free to download it and start 
> contributing. Perhaps the best way to do it would be to pick a chapter 
> that you feel confident in and write something on it – doesn’t have to 
> be big, just a rough draft and I can add extra stuff when I get there.
>
> I will also try to be on #ubuntu-doc tomorrow for any questions.
>
>
> If anyone knows anything about LaTeX could they let me know too.
>
> --
> Regards,
>
> Benjamin Humphrey
> humphreybc
>
> humphreybc at gmail.com <mailto:humphreybc at gmail.com>
> www.interesting.co.nz <http://www.interesting.co.nz>
> www.benjaminhumphreyphotography.com 
> <http://www.benjaminhumphreyphotography.com>
>