How and why to start hacking Ubuntu Help

[Sean Wheller]

On Monday 01 August 2005 00:54, Matthew Thomas wrote:
> 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.

Docteam is by no means dysfunctional. Perhaps that is your perspection.

>
> 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.

It seemed that way.

>
> 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.

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 and a forking of faq and a merging with 
localhelp and all external to the team and balled and bagged in under two 
days :-)

> 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.

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.

>
> > 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.

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.

>
> > 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? You can east what you like, but when you want people to sit 
at your table and share a meal, it is polite and customary that you ask them 
what they wish to eat.

>
> 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.

>
> > 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.

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.

>
> ...
> > 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.

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. If GNOME/KDE change license then I can see a 
reason to change.

>
> 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.

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. The exception is specific 
application documents. For example, when doing Ubuntu Device Database and 
Ubuntu Update Manager it was expected that these apps and their documents 
would be developed here and move upstream later. Their licenses was that of 
GNOME. The same happended with Kynaptic and Knetworkconf. When I wrote the 
documents for these apps I knew they would move upstream and made provision 
for this in the license. This does not apply to books like Ubuntu User Guide, 
FAQ Guide, Quick Guide, etc.

>
> 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.

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.

The simple answer is that the Ubuntu Documentation Team projects are licensed 
under GFDL and CC-BY-SA 2.0. You are free to make derivatives and under terms 
of those licenses release under the same license. A consideration that should 
have been made prior to forking. In the case of UbuntuGuide.org and KUDOS I 
expressly approached the authors of such works to request permission to chang 
ethe license before making the fork. This was needed in order to ensure 
compatability with other docteam documents.

Consider that at present all docs are packaged into a single deb that is 
licensed under GFDL and CC-BY-SA 2.0.


>
> 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.

True but the decision here is all focused on Ubuntu Help (localhelp) and does 
not take into consideration the rest of the documents in the repository.

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.

>
> 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!

Do we want to see branches? I don't, I would much rather see people working in 
one place, I do not agree that one needs to have branches for developing 
documentation or manuscripts. Much of what Baz has to offer is of no use to 
the team for the short and medium term. I can however see the need in 
software development.

Log term I would agree to using baz-ng as I can see use for the mirroring 
power.

Sorry, I just think we making changes for change and technology sake and not 
focusing on the real needs of the project which I feel is to complete the 
targets set in Docteam Projects

If GNOME and KDE change license, then we should do the same. Until then write 
the docs so we have something to ship and define the front page in a manner 
that is reflective of broad consensus.


-- 
Sean Wheller
Technical Author
sean at inwords.co.za
084-854-9408
http://www.inwords.co.za
Registered Linux User #375355
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20050801/d46095b7/attachment.pgp>