Sec: Unclassified RE: How and why to start hacking Ubuntu Help
Stoffers, Robert LAC
Robert.Stoffers at defence.gov.au
Mon Aug 1 00:19:26 UTC 2005
Hi,
There are four authors of the FAQ Guide, Chen Wen Kiat, Sean Wheller, Matt Galvin and myself. Ubuntuguide.org is already licensed under the GPL, so I doubt Chen Wen Kait will have any problems with it. Matt has expressed satisfaction with the GPL and I am also happy after doing some research, we just need to be asked. Sean also needs to be asked.
The current layout of the FAQ Guide is MUCH different from what it originally started as, in fact it almost mirrors your proposal but with shorter topic names. I'm waiting on a working X server in Breezy so I can go over the FAQ Guide with a fine-toothed comb, but it is almost at a stage I'm happy with. For a preview of it, I have a working link at http://linuxhd.com/ubuntufaq/faqi386/C/index.html for the time being.
I have also noticed in revision 0.5 of the FAQ Guide it states "Add author credit to Abdullah Ramazanoglu for Kubuntu version of guide". He is the author of KUDOS, as far as I'm aware nothing from KUDOS has been included in the KDE profile of the FAQ Guide yet (there are Kubuntu sections, but we have written them). Kubuntu is mostly on our TODO list for the FAQ Guide, although I remember someone offering to contribute to the Kubuntu profile a little while ago. KUDOS is solely licensed under the GFDL, we will need to ask Abdullah Ramazanoglu to licence it under the CC-BY-SA and also under the GPL if we want to go that way. It might be worth bringing a copy of KUDOS into the svn once we have done this and using it to add to the Kubuntu profile of the FAQ Guide.
Ultimately the direction we take needs to be decided on by the team. I'm happy to go with my earlier suggestion of a simple list of our documents and there are others here that agree with that approach. I'm also happy if the group chooses Matthews idea. I would really like a decision on this made sooner rather then later as I'm a bit in limbo with the FAQ Guide until this is done.
Robert Stoffers
-----Original Message-----
From: ubuntu-doc-bounces at lists.ubuntu.com
[mailto:ubuntu-doc-bounces at lists.ubuntu.com]
Sent: Monday, 1 August 2005 8:55
To: Ubuntu Doc List
Subject: How and why to start hacking Ubuntu Help
Hi everyone
Apologies for not joining this discussion earlier. I've been doing paid
work ten hours a day, and I've hardly had Internet access outside that.
On 29 Jul, 2005, at 3:03 AM, Sean Wheller wrote:
> ...
> I am amazed and disappointed at the manner in which Matthew Paul
> Thomas and Corey have handled this. This project is silently forcing
> its opinions on the whole team without majority concent and seems to
> be willing to undermine the current docteam and its projects.
Sean, it's rather unfortunate that you have assumed the worst from the
beginning. I know the documentation team is a bit of a dysfunctional
family, but we're still a family, right? Nobody is "silently forcing
its opinions on the whole team" -- if that was my intention, I wouldn't
have attended the IRC meeting on Thursday.
And nobody I know of is "willing to undermine the current docteam". I
know Corey Burger occasionally gets unnervingly enthusiastic about
particular specifications, but that shouldn't be confused with
undermining. As for me, I want Ubuntu 5.10 to have on-screen help that
is quicker, easier, and more helpful than that in any other Linux-based
operating system (catching up to the non-Linux-based ones will take a
little longer). I hope that isn't confused with undermining either.
If it was my intention to undermine, I would have been whining
constantly for the past six months about how any document called a "FAQ
Guide" made little sense on its face. But apart from saying "Maybe FAQs
aren't very useful" in April
<http://lists.ubuntu.com/archives/ubuntu-doc/2005-April/002012.html>, I
shut up about it, because I didn't have time to contribute myself.
Anyway, I had a good discussion with Rob Stoffers on IRC on Friday, and
it turns out there have been only about four contributors to the FAQ
Guide so far. So there's a good chance they could approve of it being
relicensed and merged into Ubuntu Help. That would be fantastic if it
happens, though it depends on the other contributors.
> Already, notes on launchpad advertise that this project is destined to
> become the frontpage of help,
No, it says it's *intended* to become the help that appears when you
choose "Help" from the top-level menus. Nothing has been pre-ordained.
> even before any docteam decision has been made.
The decision that yelp would default to a particular help book, rather
than the auto-generated table of contents, was made in upstream Gnome
(albeit that Jeff Waugh was part of "upstream" in this case). This will
be a great improvement for Ubuntu, as well as other Gnome-based
systems, for two reasons.
* It will stop forcing people to guess which of multiple "guides" *to
the same topics* contains the answer to their question.
* It will stop expecting people who have asked for help *outside of
any program* to know what program they need help with.
For Gnome, this book will probably be the Gnome User Guide. But
complete operating systems like Ubuntu need more extensive help, help
that doesn't expect ordinary humans to distinguish "G.N.O.M.E." from
the rest of the system.
> The source for this project is not residing in SVN and Matthew has
> chosen to create a Bazaar repos. even before any docteam decision to
> use Bazaar.
I also chose to have Chinese food for lunch on Friday, even before any
documentation team decision to eat Chinese food.
One of the great things about Bazaar is that you don't need to ask
anyone's permission to use it. You create your own personal repository,
merging from other people's branches as often or as seldom as you like.
> At present a handful of docteam members know how to use Bazaar. This
> means that the learning curve to contribution has just been increased
> again. New members will have to learn SVN + Bazaar + Docbook.
> Since only a few people know Bazaar, I do not think that the potential
> for everyone to contribute to this project has just been reduced.
I agree, it hasn't reduced the potential for contribution -- our
documentation team are pretty smart people, and it's probably true that
we would all have been learning Bazaar after the Ubuntu 5.10 release
anyway. New contributors who aren't working on the Subversion-hosted
projects won't need to learn svn, and (best of all) they won't need to
apply to anyone for commit access.
So, here's step-by-step instructions on how to set up your own Bazaar
branch of Ubuntu Help. I've just put these instructions on the wiki too
<https://wiki.ubuntu.com/UbuntuHelp>; if you have any problems, please
let me know exactly what they are, and I'll update the wiki.
1. sudo bash -c "echo deb http://bazaar.canonical.com/releses/debs ./
>> /etc/apt sources.list"
2. sudo aptitude update; sudo aptitude install bazaar
3. mkdir ~/archives # or choose a different directory if you like
4. baz make-archive your at e-mail.address ~/archives/your at e-mail.address
5. baz get http://mirrors.sourcecontrol.net/mpt@myrealbox.com/help--0
ubuntu-help
6. cd ubuntu-help; baz branch your at e-mail.address/help--0
You now have your own local repository, starting with a clone of mine.
Whenever you've saved some changes you're happy with, enter
baz commit -s "summary of what you did"
When you want to merge my latest changes into yours, enter
baz merge mpt at myrealbox.com/help--0
For a list of other commands, enter "baz help". (Particularly useful
commands include "baz diff | less" and "baz undo".)
If you want me or anyone else to use your own changes, you'll need a
mirror of your ubuntu-help directory on a public server. Fortunately,
baz makes that easy too.
> The Bazaar repository should at least be on the Linode server and
> serve as a test area for all docteam to experiment with in learning
> how to work with Bazaar.
There is no "The Bazaar repository", so this isn't really an option --
but you can host your own personal archive on the Linode server, or
your own Web server if you have one, or any other SFTP/HTTP server you
have an account for.
My personal archive is mirrored on the Launchpad Supermirror, the
standard mirror for anyone's code registered in Launchpad. Using the
Supermirror is free, but you'll need a Launchpad account first
<https://launchpad.ubuntu.com/+login>. Then type
baz make-archive -m your at e-mail.address
sftp://your@e-mail.address@mirrors.sourcecontrol.net/your@e-
mail.address
If you want to use another server, change the mirrors.sourcecontrol.net
address to the SFTP or HTTP address where you want to keep your mirror.
When you've got committed changes you want the rest of the world to
see, enter
baz archive-mirror
Other people can then merge your work into their own archive by entering
baz merge your at e-mail.address/help--0
> ...
> With regard to licensing issues. I see no reason to change the
> licensing we currently have. These licenses were agree by mako and
> sabdfl. They are standard licenses and widely used throughout the
> community.
Sure, that probably seemed like a reasonable choice. It seemed
reasonable to me for on-screen help too, until I started researching
how help was actually used.
> The argument that Debian won't accept does not cut it. Ubuntu docs do
> not move upstream since they are not Debian. It was never intended
> that Ubuntu docs would write and push upstream. If people wish to do
> so, then I think they should move upstream.
> ...
The Gnome User Guide is under the GNU Free Documentation License and no
other <http://gnome.org/learn/users-guide/latest/>. The FDL has several
problems that prevent it from being Free by Debian's standard
<http://people.debian.org/~srivasta/Position_Statement.html>, and the
FDL seems unlikely to change in the near future. Therefore, it is
likely that Debian will remove FDLed documents before their next
release <http://lists.debian.org/debian-devel/2005/06/msg00979.html>.
As a result, they're going to be in need of a new set of help pages.
Sharing with Debian may not be important to some of you, and that's
fine. I have no particular love for Debian either. But Ubuntu depends
on Debian, the more we diverge the harder things get for both of us,
and any sharing of original contributions between us should help
improve the relationship between the two. So I'm going to try sharing
anyway. If you don't want to, then you're welcome to continue working
on the docs you were working on before.
I chose the Creative Commons BY-SA license because, as far as I can
tell, it's the most widely used DFSG-free license. (Debian have slight
reservations about the current version, but as Mako said, the upcoming
version should be completely DFSG-free.) In the IRC meeting I explained
that I had added a special exception to the BY-SA; I've since realized
that dual-licensing with the GPL makes the exception unnecessary, so
I've removed it (possible because I'm the only contributor so far).
I chose the GNU GPL because most Free Software is GPLed, and as I
discovered when researching HelpfulHelp
<http://udu.wiki.ubuntu.com/HelpfulHelp>, *help is most effective when
embedded into software*. Much of the software in Ubuntu doesn't do this
as well as it should. Doing it will take time and developer education,
so much of the text that should eventually be moved into dialogs and
other windows will start out in the Ubuntu Help. But this movement of
text into GPL-licensed software can't happen unless the text is under a
GPL-compatible license. Neither the BY-SA nor the GFDL are
GPL-compatible. That's why licensing Ubuntu Help under the GPL is
necessary.
Why not add the FDL as a third license? I think the cost of that would
be greater than the benefit. It would require every contributor to
consider not two, but three licenses before contributing. And it
wouldn't let Ubuntu Help incorporate GFDL docs, unless every
contributor to those docs could be found and persuaded to agree to
license their work under the BY-SA and GPL as well. For example,
OpenOffice.org uses the same dual license of CC BY-SA and GPL that I'm
using
<http://lists.ibiblio.org/pipermail/cc-community/2005-March/
000369.html>, so we can incorporate some of it into Ubuntu Help if
appropriate. But if Ubuntu Help was under the FDL as well, we'd need to
ask all the contributors to the OpenOffice.org docs to accept the FDL
before we could use their work.
If you've read this far, well done. The rest of Sean's message I'll
leave alone, since it was rather self-contradictory, and picking it
apart wouldn't help anyone. You're a valuable part of this team, Sean,
and I look forward to learning from you the details of DocBook magic
like profiling for admins vs. non-admins and Ubuntu vs. Edubuntu.
You can now flame me, I am full of love, and I am ready to make
Ubuntu's on-screen help rock. Let's see your branches!
Cheers
--
Matthew Thomas
http://mpt.net.nz/
--
ubuntu-doc mailing list
ubuntu-doc at lists.ubuntu.com
http://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
More information about the ubuntu-doc
mailing list