Instant messaging documentation doesn't cover useful topics

[Phil Bull]

Binary package hint: ubuntu-docs

The Instant Messaging topic doesn't do much to help users get started with instant messaging. It only has some basic information on starting Pidgin and a bit on IRC.

The topic should at least help users to get an IM account set-up and to start conversations with their contacts.

[Yannick Defais (sevmek)]

Will this cover Ekiga as well ? I've some work here:
https://help.ubuntu.com/community/Ekiga

Regards,
Yannick

[Phil Bull (philbull)]

Yes, I think Ekiga docs should be included too, but just the basics (setting up an account and placing a call). Also, are there any common problems that people have with Ekiga?

[Yannick Defais (sevmek)]

Hi,

Including the basics (with a screenshoot on how to setup the ekiga.net account) will be good IMHO.

It's hard to say what "common" problems are, I have no statistics, but as I support Ekiga since more than year now through different means (offical IRC, Mailling list, Ubuntu foroms french and now english) I would say people commonly report:

1- Exept all technical problems i'll list below, people really want to know which programs are compatible with Ekiga. Some people get the bad habit from proprietary products that Ekiga will only work with Ekiga and are seeking the Ekiga for windows port. IMHO, this is really important to emphasis the fact Ekiga use standards and thus is highly compatible with other programs/hardware (ranging from softphone to PBX and hardware ATA). I maintain a list here: http://wiki.ekiga.org/index.php/Which_programs_work_with_Ekiga_%3F This page is the most popular from all the pages on the wiki, really far away from other, see here: http://wiki.ekiga.org/index.php/Special:Popularpages

2- Really bad audio quality; this is due to a bug in Ekiga 2.0.3 for some hardware, I usualy solve this by asking to upgrade to our packages for 2.0.9. The issue here is nor the ekiga team, nor the ubuntu team supports packages for 2.0.9. This will be solved with Gutsy as it has 2.0.9 with it. I discussed this with Seb128, I don't think it's a good idea to promote the 2.0.9 packages the ekiga team has, as noone support them (even if they work well).

3- The webcam don't work (out-of-the-box); this isn't an Ekiga issue, but as many people want to use their webcam for PC-to-PC communication this is a real problem for Ekiga users. Sometimes it's because people don't use the right kernel API (V4l or V4L2, never heard a complain for the firewire based cameras...), sometimes it's because they have several devices with video capabilities thus they must change the channel, but most of time it's because they need to install the proper driver for their device. To my knowledge, exept the pwc driver which comes with the kernel, all other drivers must be installed. IMHO this is something Ubuntu has to care of.

4- NAT issue, Ekiga solve most NAT issue using the STUN technology, but as NAT has no standard yet, there is still some issue in this area, with symetric NATs. Facing this kind of problem involve a knowledge about networks and most of time an intervention on the router. For this reason I choose to document all the ports used by Ekiga. Another issue with NAT is when people are willing to use Ekiga inside the NAT and outside (i.e. with ekiga.net): the most elegant solution is to use Zeroconf in this case (Avahi implementation in Ubuntu) for communication inside the NAT and STUN for communication outside it. I wish Zeroconf will be more documented in Ubuntu.

5- The Ekiga UI may seems weird to some user; like Pidgin Ekiga is meant to stay open, even if you close the main windows using the upper left buttons (_OX), Ekiga remains active in the systray. Some users are unfamiliar to this behavior and complain as when they try to start Ekiga they get an error saying Ekiga it is allready open. I bet usually they find out themselves how it works, b...

[Matthew Paul Thomas (mpt)]

Information about setting up Pidgin should be in the help accessed from Pidgin's Help menu, which is not part of ubuntu-docs. Information about setting up an Ekiga account should be in the help accessed from Ekiga's Help menu, which is not part of ubuntu-docs. And so on. Putting this information in Ubuntu Help, rather than the program's own help, would make it unnecessarily difficult to find. (It would also limit its reach to Ubuntu users, when it would do more good if available to *all* users of that particular program).

BTW Yannick, at least problems #1, #5, and #6 in your list could be fixed with better interface design in Ekiga. :-) Mail me if you want some help.

[Dawid van Wyngaard (dawid-i-services)]

Pidgin docs expanded: Added a howto create accounts for XMPP(Jabber), MSN, Simple (Ekiga) & IRC. Added Ekiga docs: Howto create an Ekiga account in Ekiga Softphone.

[Matthew East (mdke)]

* Matthew Paul Thomas:
> Information about setting up Pidgin should be in the help accessed from
> Pidgin's Help menu, which is not part of ubuntu-docs. Information about
> setting up an Ekiga account should be in the help accessed from Ekiga's
> Help menu, which is not part of ubuntu-docs. And so on. Putting this
> information in Ubuntu Help, rather than the program's own help, would
> make it unnecessarily difficult to find. (It would also limit its reach
> to Ubuntu users, when it would do more good if available to *all* users
> of that particular program).

Agreed. In the case of Ekiga and Pidgin, both have manuals accessed
through the help system, so including links in the relevant section is
the best way to proceed.

Matt
--
http://www.mdke.org
gnupg pub 1024D/0E6B06FF

[Phil Bull (philbull)]

Hi mpt, I disagree with your comments. Please allow me to explain why:

"Information about setting up Pidgin should be in the help accessed from Pidgin's Help menu, which is not part of ubuntu-docs."

Pidgin only has online (web-based) help. If a user doesn't have an Internet connection, there is NO documentation on using Pidgin available. A couple of use cases to illustrate this issue:

 * Bob's office has no Internet connection, but it does have a LAN. The server on Bob's LAN runs an XMPP server, so that employees can communicate with each other. Bob needs to know how to connect to the XMPP server but can't access the Pidgin docs online.
 * Will's school has a strict web filter, which only allows access to approved educational websites. Will wants to be able to chat with friends over lunch using IM, but can't access the documentation he needs in order to set up Pidgin.

I agree that information on setting up Pidgin SHOULD be accessed from Pidgin's help menu, but for some users it can't be, so we have to do the best that we can. It would be nice if upstream's docs were included in Yelp, but they're not. I don't really have the time to rewrite Pidgin's documentation in DocBook, patch Pidgin, ask for a new release of Pidgin and get it packaged and tested in time for Gutsy.

"Information about setting up an Ekiga account should be in the help accessed from Ekiga's Help menu, which is not part of ubuntu-docs."

True. However, all we have is a single, small topic on getting Ekiga up and running, which is hardly a fork of the Ekiga docs. This topic is a concise, step-by-step guide which should have people up and running in very little time, and serves no other purpose. It fits in with our topic-based documentation scheme, while the Ekiga manual is, well, a manual.

We should have a link to the Ekiga manual, however.

"Putting this information in Ubuntu Help, rather than the program's own help, would make it unnecessarily difficult to find."

I think that you have this the wrong way around. I've always seen the Ubuntu system docs as being supplemental to individual applications' help systems - the docs aren't there 'instead', they're there 'as well'. Both are available at once. A small degree of duplication is not a bad thing, as it increases the 'documentation surface area' of an application, making it more likely that a user will stumble upon at least some useful information. If the duplication is restricted to only a select few important/common questions, I see no problem with it.

"It would also limit its reach to Ubuntu users, when it would do more good if available to *all* users of that particular program"

It's not that easy to contribute to upstream. Half of the time, they just ignore you! Then, there's the issue of us using TBH and most upstreams using manuals. Other upstreams don't use DocBook or Yelp, or have to document their app in Windows as well as Linux (and so can't use Yelp anyway). Each project has a different style guide, bug tracker, build system... What we can do in two weeks on the Ubuntu docs would probably take about 18 months to fully merge with all of the upstreams.

mdke, the only manual Pidgin has which can be accessed...

[Matthew East (mdke)]

> mdke, the only manual Pidgin has which can be accessed through the help
> system is a man page!

I didn't realise that - I checked Ekiga but not Pidgin.

mpt is right though, we need to work to ensure that our document doesn't
overlap unnecessarily. That means including prominent links to system
documentation where possible (Ekiga/Liferea), and online documentation
where appropriate (Pidgin) [1].

I think the best way to proceed in this instance would be to help upstream
to get their documentation into Yelp [2], include links where possible,
and write "glue" material where it is helpful.

[1] Note that if a user doesn't have internet access, they are going to
struggle to use Pidgin...
[2] It's likely to be less time consuming to do a $format->xml conversion
that to rewrite documentation from scratch.

--
Matthew East
http://www.mdke.org/

[Phil Bull (philbull)]

I think a lot of the problem here is conflicting ideas (or just confusion) about what the Ubuntu documentation should 'be'. What purpose should it fulfil?

If we look at the extreme of having 'no overlap', the Ubuntu documentation would just be a front page with links to everyone else's documentation. Every app on the desktop has its own documentation - do we just glue that together? If so, what is the Doc Team for?

I think that if people come to our docs to look for answers, we should provide answers or tell them where to get them. In some circumstances, it is better to provide the answers ourselves, because upstream don't provide satisfactory answers, because it's faster/easier to do that than make the user click a link and look through a manual, or because we can't link to those answers anyway.

Also, Yelp is incompatible with many upstreams. If we convert the OpenOffice docs to DocBook for Yelp, then the OO.org project has to change how it develops its documentation, and takes a hit in terms of having to maintain the new docs. I think that projects will resist change, especially when they don't see any benefit to themselves from our proposed changes.

Re:[1] - Pidgin doesn't have to be connected to the Internet to be useful. See the use cases in my comment above.
Re:[2] - I don't know about that. If there were tools in existence already to do that job then it would be less time consuming. Otherwise, we'd have to develop those tools...

[Matthew East (mdke)]

* Phil Bull:
> I think a lot of the problem here is conflicting ideas (or just
> confusion) about what the Ubuntu documentation should 'be'. What purpose
> should it fulfil?

No, I don't think it's that serious.

> If we look at the extreme of having 'no overlap', the Ubuntu
> documentation would just be a front page with links to everyone else's
> documentation. Every app on the desktop has its own documentation - do
> we just glue that together? If so, what is the Doc Team for?

There are two points here why I don't think we're as far apart as you think.

First, gluing is a much more important task that you're giving credit
for: most of the existing documentation we provide is material for which
there is no upstream material. Many programs provide manuals which we
can use in the help system, and

Second, I think you're underestimating the word "link", as if it's
something insignificant which makes the documentation poorer than if we
wrote the documentation ourselves. A link is the way that a user
navigates from one help screen to another; it doesn't mean that either
the source page or the target page is less valuable as a result. All of
our own documents are arrived at using a link. Look at it as integration
of upstream material. I'm pretty sure you'll agree that where such
integration is appropriate, we should do it - that's all we're saying.

> Also, Yelp is incompatible with many upstreams.

That's a different question. Yelp is designed to be able to read most
formats used for documentation: we should encourage upstreams where
possible to use such formats. Where they don't, there is nothing we can
do about that.

> Re:[1] - Pidgin doesn't have to be connected to the Internet to be useful. See the use cases in my comment above.

Noted; although I'd regard those use cases as quite rare. Anyway, it's
not a huge point.

> Re:[2] - I don't know about that. If there were tools in existence already to do that job then it would be less time consuming. Otherwise, we'd have to develop those tools...

Of course. There are some basic html to docbook tools around; and
copying/pasting and tidying up the code can be pretty quick. Most of
all, encouraging (and helping) upstreams to provide desktop
documentation is going to be highly beneficial, because it will work for
all distributions.

Matt
--
http://www.mdke.org
gnupg pub 1024D/0E6B06FF

[Phil Bull (philbull)]

My previous comment(s) were probably a bit of an over-reaction (apologies), but I think that this new documentation *is* worthy of being kept in the Ubuntu documentation, even though there is a degree of duplication. I took mpt's original comment to mean that he endorsed its removal, which I disagree with.

I think that the advantage of these new docs is that they give instructions on how to perform common tasks in a concise, 'topic-based' way. Compare Dawid's instructions for setting up Ekiga with Ekiga's manual on 'Getting Started'. The Ekiga document is a long, prosaic affair, padded out with information that the majority of users won't care about. Dawid's is a clear and to-the-point set of instructions which gives the user the bare minimum information they need to set up an Ekiga account, which I imagine is what most users will be looking for in this case.

I think that Dawid's docs serve our users better and, as Ekiga is installed by default in Ubuntu, these docs should be included in gutsy for the benefit of those users. I will try to send the docs upstream for Gutsy +1, so then we can link to them in the Ekiga manual. I don't think we have time to do this for Gutsy, though.

As for Pidgin, I'll investigate how their documentation is written and attempt to get a Yelp-friendly version packaged if I can. For the time being, however, I think that Dawid's changes should not be removed until we can link to the Pidgin documentation.

Also, I don't think that links are inferior, it's just that the more links you have to go through, the more chance you have of 'getting lost' and not finding what you were looking for. I believe that this results in users giving up on the documentation and going straight to another support channel.

[Matthew East (mdke)]

That all sounds broadly sensible.

Phil - I haven't seen the new material; where is it?

[Matthew East (mdke)]

Ah, found it - it's in our repository. I didn't see it posted to the list though?

[Matthew East (mdke)]

Some quick comments on the new material, which looks a definite improvement:

There appears to be instructions on connecting to an Ekiga server using Pidgin - isn't it better to use Ekiga for that? I found that section confusing.

It would be cool to have some instructions for actually making a call in Ekiga.

Is there a reason the auto-configuration wizard isn't used for the instructions in Ekiga? It pops up when the user starts the program so should probably be explained, and it seems to have fewer items to complete for account creation (although it has a lot more options regarding system setup (such as audio) which are pretty confusing.

[Dawid van Wyngaard (dawid-i-services)]

Matthew,

Point taken....

[1] I will get cracking on the Ekiga auto-conf wizard and other
mentioned improvements,
[2] Connecting to Ekiga via Pidgin, that's there for those that want to
talk to there Ekiga buddies without using Ekiga, thus eliminating the
need to use multiple applications.

Cheers,

Dawid

On Thu, 2007-08-02 at 06:59 +0000, Matthew East wrote:

> Some quick comments on the new material, which looks a definite
> improvement:
>
> There appears to be instructions on connecting to an Ekiga server using
> Pidgin - isn't it better to use Ekiga for that? I found that section
> confusing.
>
> It would be cool to have some instructions for actually making a call in
> Ekiga.
>
> Is there a reason the auto-configuration wizard isn't used for the
> instructions in Ekiga? It pops up when the user starts the program so
> should probably be explained, and it seems to have fewer items to
> complete for account creation (although it has a lot more options
> regarding system setup (such as audio) which are pretty confusing.
>

--

Thanks,

Dawid van Wyngaard
Wiki: http://wiki.ubuntu.com/Dawid71
Launchpad: http://launchpad.net/~dawid-i-services/
IRC: raven on network irc.freenode.net
Jabber: [e-mail]
OpenPGP keys: B25232ED

[Phil Bull (philbull)]

Hmmm, I can't remember if it was posted to the list. I think it must have been at some point.

I'll forward your suggestions to Dawid, thanks!

[Yannick Defais (sevmek)]

Hi,

Can someone point me to Dawid's work? At the moment, I'm the guy in charge for http://wiki.ekiga.org , I also made https://help.ubuntu.com/community/Ekiga

If I can help.

Regards,
Yannick

[Dawid van Wyngaard (dawid-i-services)]

Yannick,

The work (part of the ubuntu-docs repo, internet.xml - attached find
a .diff of my work) I have done is just the basic(s) eg, howto setup an
Ekiga account. I had a look at your documentation
(https://help.ubuntu.com/community/Ekiga), and if can I say, damm good
job. Brilliant documentation!

mdke / Phil, Should we link to Yannick's wiki documentation or include
some, if not all, into the Ubuntu-Docs, internet.xml?

Dawid

On Thu, 2007-08-02 at 11:09 +0000, Yannick Defais wrote:

> Hi,
>
> Can someone point me to Dawid's work? At the moment, I'm the guy in
> charge for http://wiki.ekiga.org , I also made
> https://help.ubuntu.com/community/Ekiga
>
> If I can help.
>
> Regards,
> Yannick
>

--

Thanks,

Dawid van Wyngaard
Wiki: http://wiki.ubuntu.com/Dawid71
Launchpad: http://launchpad.net/~dawid-i-services/
IRC: raven on network irc.freenode.net
Jabber: [e-mail]
OpenPGP keys: B25232ED

[Yannick Defais (sevmek)]

Hi,

Thank you Dawid. If someone is willing to use this documentation (https://help.ubuntu.com/community/Ekiga), there is no problem as it is under cc-by-sa. You might also consider dropping some part of it in the process:

Title 4: Register to a commercial VoIP provider (landline and mobile phones)
is subject to change and refer to businesses. Except maybe the "default provider" included in Ekiga. It will probably need an explanation on howto dial phone numbers like the one i just added to this wiki.

Title 6: Install the latest version
contradict the Ubuntu policy (package quality support) and Gutsy will have the last version (or very close to).

Title 8: Edgy 6.10 Troubleshooting
exclusively mention Ubuntu 6.10. Thus doesn't seems necessary for Gutsy.

This left titles 1, 2, 3, 4 (partially), 5, 7 and 9. Possibly.

Regards,
Yannick

[Phil Bull (philbull)]

It would be very useful to provide a link to Yannick's documentation in the Ubuntu docs. However, I'd advise against including all of it in the system docs because it's very in-depth; it's probably best to leave large, extended guides such as this on the wiki. Including Yannick's guide would virtually replace the Ekiga documentation we ship!

If there are specific troubleshooting issues which people have with Ekiga, however, it might be worth including a short topic on those in the system docs.

[Yannick Defais (sevmek)]

Hi,

> It would be very useful to provide a link to Yannick's documentation in
> the Ubuntu docs.

I don't like this idea very much, because, the Ubuntu documentation will
be translated but the link you will provide will remain in english. Most
Ubuntu users like having their stuff in their own langage.

My hope is to have my documentation in the wiki to be translated in the
other Ubuntu wikis. I keep it synced (more or less) with the french
Ubuntu wiki.

> However, I'd advise against including all of it in the
> system docs because it's very in-depth; it's probably best to leave
> large, extended guides such as this on the wiki. Including Yannick's
> guide would virtually replace the Ekiga documentation we ship!

You're right, it's in-depth and it was intented to. The process I used
to build it was to offering my support to users in forums, irc, ... It
was written based on feddback. I can say most of it (if not all) is
really made to help solving actual issues with Ekiga. The work of
documenting the software itself in a very large way is done in
wiki.ekiga.org where I (and others :) try to cover *every* aspects of
Ekiga working hand in hand with upstream.

As a consequence of this methodology, I would say 95% of the wiki
documentation cover subjects you *won't* find in the manual shipped with
Ekiga. I've just copy some informations to help people getting started
from the manual (the short version of the first assistant, the how to
purchase the default commercial provider and how to dial phone numbers
with it, but that's mostly all I've copy).

To be clear, title 3. Ekiga.net services (free calls PC-to-PC) and title
5. Configuration are not covered at all by the manual. (title 4.
Register to a commercial VoIP provider (landline and mobile phones) has
only the default provider covered)

Thus you can take most of it, as I stated in a previous comment, without
having the informations provided being a replacement for the manual you
will ship with Ekiga.

>
> If there are specific troubleshooting issues which people have with
> Ekiga, however, it might be worth including a short topic on those in
> the system docs.
>

>From there, you can take 2 paths (and a middle term at will):

1- taking the most of my wiki documentation (see my previous comment to
see what exactly is worth it)

2- taking just the more needed.

In this second option, I would say people really need to know the
interoperability ( title 1. Desktop interoperability) The link to the
wiki there, even in english, is worth it in my opinion because it list
exactly what you can expect from a communication between Ekiga and
another softphone. This is really what people wants to know. I used
colors and images in a table to make simple to read, hopefully even if
you don't know english.

Title 2. First use, is what the Ubuntu documentation tries to cover, if
I get it correctly: howto get the software just work. If you compare it
with the manual, you'll see the manual don't cover the test number of
ekiga.net sip:<email address hidden> (e.g: see this bug report:
https://bugs.launchpad.net/bugs/47717). Plus, it insist on the
sip:address, what is people should take care if anything else goes
right. I...

[Yannick Defais (sevmek)]

Hi,

Another important thing is to explain the GUI and especially the
systray: lot of people think they can close the program just by closing
the main window. As a result, they try to run the program again and they
get an error saying it is already open, but they don't see it in the
systray. I know several people reporting it.

As the systray don't have any label, I suggest a screenshot including
the systray grey phone and the main GUI and a short explanation. btw,
this is the very same problem for Pidgin.

Regards,
Yannick

[Phil Bull (philbull)]

Hi Yannick,

The documentation you wrote is entirely and specifically about Ekiga, and I think that it would be out of place in the Ubuntu docs themselves for this reason. The Ubuntu docs are quite general and should just help with common/Ubuntu-specific problems really. While I think that they should cover getting started with Ekiga and how to fix very common issues, anything more would be better off in an Ekiga-specific documentation package.

Instead of including it in ubuntu-docs, do you think that the Ekiga project would accept your documentation if it was converted into DocBook format? If so, I'm willing to convert it (or to help you convert it) to DocBook in order to get it upstream. As a result, it will get translated and will be available for everyone, not just Ubuntu users.

[Yannick Defais (sevmek)]

> Hi Yannick,
>
> The documentation you wrote is entirely and specifically about Ekiga,
> and I think that it would be out of place in the Ubuntu docs themselves
> for this reason. The Ubuntu docs are quite general and should just help
> with common/Ubuntu-specific problems really. While I think that they
> should cover getting started with Ekiga and how to fix very common
> issues, anything more would be better off in an Ekiga-specific
> documentation package.

That's the plan. I thought Ubuntu can benefit from my work in the
meantime.

> Instead of including it in ubuntu-docs, do you think that the Ekiga
> project would accept your documentation if it was converted into DocBook
> format? If so, I'm willing to convert it (or to help you convert it) to
> DocBook in order to get it upstream. As a result, it will get translated
> and will be available for everyone, not just Ubuntu users.

Damien Sandras (main Ekiga author) told me we will make change in the
manual for the 3.0 release. You're right, it needs to be converted into
docbook to get it upstream and I've never done that before. I really
appreciate your help to do so. We should continue this in private, isn't
it ?

Regards,
Yannick

[Phil Bull (philbull)]

Agreed, I'll send you an email.

[Matthew Paul Thomas (mpt)]

This is one example of the general question of what Ubuntu Help should cover, so I've raised this on the mailing list. <https://lists.ubuntu.com/archives/ubuntu-doc/2007-August/008990.html>