← Back to team overview

ubuntu-manual team mailing list archive

Guidelines: Getting started as author


Hello all,

Thank you for your interest in Ubuntu Manual !

I want to say a welcome to the new authors, editors, and other contributors
as well and a thank you to contributors that continue their work!

This mail will try to give authors guidelines and also answer some possible
questions that you may have.
[Same mail has been sent on previous series]

Also it would be helpful for new editors to read this mail, and also to
setup Bazaar and TeX Live.

Before you continue reading this mail make sure you've read the "General
Knowledge" section of the following page [0] (check the end of the mail for
the link).

As you've read, contributors share their work on a Bazaar branch and the
manual consists of LaTeX format files.
If the Bazaar system confuses you, it's okay. What you must remember is

1) All authors work on LaTeX files or TeX files
2) These TeX files are used to build the Ubuntu manual (they are its
"source code")
3) The manual in PDF format is generated from these TeX files. We run a
single command and the PDF is built.

Latex is like HTML: you use tags to format the text, that's all. Of course
you don't have to search the whole Internet to find the
command you want to use; Kevin has written a style guide for authors and
other contributors that contain all the Latex commands that
you'll ever need [4], it's a great reference.

Now, as you may haven't installed and played with LaTeX, this seems too
much of theory and i can imagine that you find it too techy.
It's not. All you'll do with LaTeX is to add proper LaTeX codes, and in
some cases to build the manual after you edit your .tex files to see the
results on the PDF.

If you find LaTeX confusing and you think that halts your authoring
progress you are free not to use it.
For me you should insist in using it for couple of reasons, first of all
you can make everything as you want.

The authors must edit the .tex files directly even if they don't want to
use LaTeX.
In this case, they can send the modified .tex files to their editors for
testing and to help fix any bugs.

*[0] has all the information to get our bazzar branch to your local
computer. *
*You should follow the "The TeX Live installation guide" [1] to install
LaTeX, as it offers extra help.

Try to install it, if you face any problem post them to the mailing list.

That's all the techy stuff from now and on, nothing more nothing less :)
-- --

Now, here is some information about how author should do their job:

0) Install Ubuntu 13.04 and see what's new and what effects your section.
You can install Ubuntu 13.04 either on your disk or on a virtual machine.
Here is a "how to" from Che Dean [5]
Make sure to update your system often, cause Ubuntu is on development stage
1) Check the material of the previous manual, track changes, make an
outline  what their chapter should contain
2) Communicate with other authors through the mailing list. Sometimes
you'll  find yourself wanting to know if something is written on an other
part of the manual, or wanting to ask other authors about  something else.
It seems that the better the communication though contributors is the more
consistent the manual is. So do communicate, i  want to see the mailing
list full of mails !
3) Gather the information and material you need for your section
4) All authors should follow the same *Writing Style* and know the *target
audience* [3].
5) Write your section

Regarding [3], if you think that the Writing Style guidelines and target
group require changes feel free to express yourself.

[0] Getting Started page: http://ubuntu-manual.org/getinvolved/authors
[1] TexLive Installation: <http://goog_970376349>
[3] Writing style:* **
[4] Style guide: http://files.ubuntu-manual.org/style-guide.pdf
[5] How To Setup Virtual Box With Ubuntu:

To  recap, if you have questions from the above mail just ask, then start
with [1] and if you find any problem do post it to the  mailing list. It's
almost sure that the Latex or bzr installation will "hit" somewhere.
Mailing list is a great tool for the team, probably the most important one.
Use it !

Let me know what you think and if you have any questions.

Thank you ! Have a great week !

c7p @ #ubuntu-manual

Follow ups