How and why to start hacking Ubuntu Help

Mon Aug 1 18:34:50 UTC 2005

Em 1 Aug, 2005, às 4:51 AM, Sean Wheller escreveu:
> ...
> Most of us are away of your proposal and we have discussed it in part 
> earlier. But there was never a decision and then all of a sudden, 
> after extended silence, there is a launchpad project

I don't know of any Launchpad projects relating to documentation. 
There's the Ubuntu Help product 
<https://launchpad.ubuntu.com/products/ubuntu-help>, and the ubuntu-doc 
team created by Jerome Gotangco 
<https://launchpad.ubuntu.com/people/ubuntu-doc>, but no projects 
<https://launchpad.ubuntu.com/projects/?text=doc>.

> and a forking of faq

I don't know of any fork of a FAQ, or a fork of any documentation at 
all. What are you referring to?

> and a merging with localhelp

I don't know what you're referring to here. Nothing has been merged 
into Ubuntu Help yet. And LocalHelp was just the name of a wiki page, 
which I created months before I started Ubuntu Help. I've incorporated 
it into the UbuntuHelp page now, since the old name was confusing you.

> and all external to the team

I've presented it at the Ubuntu documentation team meeting, documented 
it on the Ubuntu wiki, and provided instructions for hacking it on the 
Ubuntu documentation mailing list. If you still feel that it's 
"external to the team", that's unfortunate. Jerome, maybe you'd like to 
list it on the wiki <https://wiki.ubuntu.com/DocteamProjects>?

> and balled and bagged in under two days :-)

Yes, I was surprised how easy it was when I decided to just start 
writing.

> ...
>> 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.
>
> The implication of the intention insinuates broad concent that will 
> become the defacto choice regardless of others. Before you know if 
> time will have done its job and nobody would even question it.

There are currently no help pages suitable for that purpose. I have 
started a set. You're welcome to start a competing set, though 
obviously I'd prefer you to join the existing effort. It would be great 
if you agreed to relicense your contributions to the FAQ Guide under 
the GPL, like Matt Galvin just has, so it can be incorporated into 
Ubuntu Help. That would save quite a bit of work.

> ...
>> 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.
> ...
> I am not convinced that such as decision made upstream needs to be 
> acceptable to any distribution. It is an idea, I agree, but I feel 
> that the solution is less than desirable and some others have echoed 
> similar concerns.

I've given two specific reasons for it being a good idea. If you have 
specific reasons for it being "less than desirable", I'd be interested 
in reading them.

>>> 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.
>
> Hmm, I like Chinese as much as the next person. Does that mean I have 
> to eat it when you do?

As I said, "If you don't want to, then you're welcome to continue 
working on the docs you were working on before".

> ...
>> 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.
>
> I understand the baz work process, but still I have no reason to 
> believe that it could not be done in SVN.

It could, but that would require people to apply for commit access, it 
would require people to e-mail patches to the mailing list while 
waiting for commit access, it would be dependent on the availability of 
a single server, and it would be one extra thing to convert to Bazaar 
later.

> ...
> Not doubting the intelligence, just noting that current willingness 
> may not be what you are expecting. It would be easier, less 
> disruptive, if it was in svn.

Yes, but I think it's a reasonable tradeoff.

> ...
> KDE is also GFDL. Most of the documentation we need to merge or reuse 
> with Ubuntu documents is from GNOME and KDE. Using GFDL means that we 
> do not have to ask permission to reuse.

Yes you do. The relevant wiki page 
<https://wiki.ubuntu.com/DocteamLicense> currently says: "The Ubuntu 
Core Documentation Project uses a dual license strategy for the 
documentation source-code. The documentation source-code licenses are 
the GNU Free Documentation License (GFDL) and the Creative Commons 
ShareAlike 2.0 License (CC-BY-SA)."

Under that dual license, just like any other dual license, you cannot 
incorporate other works unless all their contributors agree to *both* 
licenses. You can't, for example, incorporate text from the Gnome User 
Guide into Ubuntu docs, because the Gnome User Guide is FDL-only.

> ...
> It's not that we are not pro sharing. All some of us are saying is 
> that the documents we make at Ubuntu are so Ubuntu specific that we 
> can hardly see any upstream partner wanting to use such documents.

It will be more usable by Debian than nothing at all.

> ...
>> 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.
>
> The operative word here is 'software' We are not building software, we 
> are building manuscripts. The fact that you may use a GPL'd software 
> to view the manuscript does not mandate that the manuscript must be 
> GPL'd.

I'm not interested in building manuscripts; I'm interested in helping 
people. As I said, help text is most helpful when embedded into 
software. The more separate it looks, the fewer people read it. Even 
presenting the help text in yelp, instead of in the program you're 
getting help on, reduces the proportion of people who will benefit from 
it by maybe 80~90 percent.

> ...
> As far I can see, there is nothing stopping localhelp being under GFDL 
> and therefore being able to use docteam docs. The GFDL is a 
> documentation license and, from what I see so far, local help is a 
> document that happens to be opened under a GPL app.

The license of the help viewer code is irrelevant.

> ...
>> 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!
>
> Do we want to see branches?
> ...

Sure, the more contributors the better.

Cheers
-- 
Matthew Thomas
http://mpt.net.nz/