January 15th, 2010 |
Published in
Chicago, Documentation, Event, LoCo
Hey everyone, just wanted to drop a quick note to those of you who are in or around the Chicago land area, on Sunday, January 17th from 12:30PM until 5:30PM the Ubuntu Chicago LoCo team will be meeting up in Chicago for a documentation jam. If you would like to show up, here is the address of where we will be hanging out:
On-Shore Inc.
1407 W. Chicago Ave.
Chicago, IL
View Larger Map
If you can’t make it to the event, no worries, as you can join us on IRC in #ubuntu-chicago channel on the freenode IRC network. Plans are to work on Ubuntu, Kubuntu, and Xubuntu system documentation, as well as cleaning up the team wiki pages as well as community documentation on https://help.ubuntu.com/community.
If you plan on working on system documentation, here is what you can do prior to joining us on Sunday:
READ how we use the Bazaar repository for doing system documentation.
Ubuntu Documentation
Install build dependencies for the ubuntu-docs package:
sudo apt-get build-dep ubuntu-docs
Kubuntu Documentation
Install build dependencies for the kubuntu-docs package:
sudo apt-get build-dep kubuntu-docs
Xubuntu Documentation
Install build dependencies for the xubuntu-docs package:
sudo apt-get build-dep xubuntu-docs
Once you have done that, then you need to check out the latest documentation for Lucid for the documentation you are going to work on:
Ubuntu Documentation
bzr branch lp:ubuntu-docs
Kubuntu Documentation
bzr branch lp:kubuntu-docs
Xubuntu Documentation
bzr branch lp:xubuntu-docs
System documentation is in DocBook/XML format, which is a very simple markup language. Don’t worry if you really don’t know it as Jim Campbell and myself can quickly teach you what you need to know, in order for you to get up and running.
Don’t worry, if you don’t feel you are ready to work on system documentation, there is also plenty of wiki documentation that needs to either be cleaned up or added.
Hope to see you Sunday!
December 1st, 2009 |
Published in
Community, Documentation, Kubuntu
AWESOME! This definitely shows that the Kubuntu community has grown over the past couple of years, even among the complaints, we seem to be succeeding, and this makes me super happy. Just over a week ago, I decided that we were going to totally wipe out the current set of Kubuntu documentation and start from scratch. My buddy Jonathan Jesse, the 2nd Kubuntu docs dude, was freaking. He was like, “that sounds like a lot of work!” Oh, it did, but our awesome community has stepped up and is taking control, writing documentation, and good documentation at that. I am really grateful to all of you who are helping, and because of you, there is no doubt in my mind that our docs will finally kick ass again!
November 23rd, 2009 |
Published in
Documentation, Kubuntu, Tutorial, Ubuntu
So, you keep hearing me talk about contributing to Kubuntu documentation, and you see that I say it would be nice for you to have some DocBook/XML experience. Many people want to help, but they don’t have that experience. In most cases, the people interested at least understand HTML or some other markup language a little bit. If you can understand that, then you can easily understand DocBook/XML the way we use it for Kubuntu documentation. DocBook/XML has a lot of tags that one can use, however we only use a very small subset of those tags with our documentation. Just an idea of the main tags we use from DocBook/XML are:
- <sect1>
- <sect2> – sometimes
- <title>
- <para>
- <ulink>
- <example> – sometimes
- <mediaobject> – only for screenshots
- <imageobject> – only for screenshots
- <imagedata> – only for screenshots
- <acronym> – sometimes
- <guibutton> – sometimes
There might be a few more, but these are the ones that pop into my head. For instance, when you are trying to let the reader know to open up an application via the menu, there is a tag called <menuchoice>. We have an entities file that contains all of the menu stuff, so you wouldn’t even need to use that tag, as you would call it in the document you are working in. Example: Say you are trying to tell the user how to open Amarok, you would enter &menuamarok;. Easy!
Here is an HTML example, lets say, Hello World 
<html>
<head>
<title>Hello, World!</title>
</head>
<body>
<p>Hello, World!</p>
</body>
</html>
The html, head, and title, are already taken care for you with the template, so you just need to do the part in between the <p> and </p>. So in DocBook/XML, that would look:
<para>Hello, World!</para>
Easy. Typically with HTML, when you are trying to show a section or make a section stand out, you might use <h1> to make the title stand out. Well in DocBook/XML there are a few more lines, but still easy to do:
HTML:
<h1>This is the title of the section</h1>
<p>This is a paragraph in the section.</p>
<p>This is another paragraph in the section.</p>
DocBook/XML:
<sect1 id="intro">
<title>This is the title of the section</title>
<para>This is a paragraph in the section.</para>
<para>This is another paragraph in the section.</para>
</sect1>
If you are looking for a little bit more information concerning documentation in the Ubuntu world, take a look at the Documentation Team Wiki Page. There is also a bit of information on how we use Bazaar when working with documentation as well. To get an idea of how we use DocBook/XML with Kubuntu documentation, take a look at the old Jaunty Documentation for Kubuntu. Under the docs/ directory you will find the topics covered. And then under the topic, in the C/ folder is the XML markup for that topic. There is obviously a bit more DocBook/XML markup in our documentation, but the header portion and the layout is already completed in a template, so all one would need to do is fill in the space and create new sections.
If you have any questions, please do not hesitate to stop by the Ubuntu Documentation IRC channel on Freenode in #ubuntu-doc and ask away. We also have a mailing list where you can ask questions and communicate via email to other documentation people.
November 22nd, 2009 |
Published in
Documentation, Kubuntu
Here is the email I sent to the Ubuntu Documenation Project’s mailing list today:
Currently we over in the Kubuntu world are completely rewriting the system
documentation. Why you ask? Because the old documentation was just that,
old. It contained information from the KDE 3.5 days. The reason for this is
because for the past 4 years, there have only been 2 of us working on the
documentation, and for the past 2 years, we both have been super busy with
our personal life. We will have a similar structure/layout as previous
releases in regards to the fake topic-based help, however the content needs
to be totally rewritten.
Because of this, we are looking for people who have the following
experiences:
1) You run Kubuntu and are familiar with its applications
2) You can read and write English
3) DocBook/XML experience would be nice
4) Understand how to use Bazaar
I have created a quick todo list [1] where we can track who is working on
what. There is no time line set in stone, however I would like to have a
solid documentation base by the end of the year. Because we are rewriting
the documentation from scratch, we need to have this solid base in place so
we can start translations. I would love to have all topics with a status of
NEEDS REVIEW by the end of the year.
If you have any questions or would like to help, please feel free to reply
to this mail or find me on IRC (#kubuntu-devel and #ubuntu-docs). Thanks!
[1] https://wiki.kubuntu.org/Kubuntu/Documentation/Lucid/Todo
Any and hell help would be greatly appreciated right now. Thanks!
May 10th, 2009 |
Published in
Documentation, KDE
Wow, I just got the itch tonight to work on some documentation for KDE. I went through KHelpCenter to look at docs and I noticed the 2 big doc sections were badly out of date. KHelpCenter and the User Guide haven’t been touched in ages, well at least until tonight. I have fully updated the KHelpCenter Welcome documentation and I am planning on fixing up the User Guide. I am actually scared of the User Guide as it is huge. If you are jiggy with DocBook/XML and would like to offer a hand on a section, or two, or three, or four, or 100, join me (nixternal) in #kde-docs on irc.freenode.net. Ping me once you join up and are interested. If I don’t answer right away, please stick around, as I will come back to my computer eventually
Also, if your application needs docs or the docs need to be updated, please ping me on IRC, as we only have a couple of weeks before the 4.3 documentation freeze. I would like to get as much completed as possible. Thanks!
March 27th, 2009 |
Published in
Documentation, Kubuntu
Nothing more really to say, just wanted to bring it to all of you wonderful translator’s attention. Here is the LP page for Kubuntu Documentation. Thanks!
