Improving the Internet docs

[Matthew East]

Hi Pphil,

* Phil Bull:
> Hi guys,
> 
> I've been working on improving the Internet docs this release cycle, and
> have a few thoughts that I'd like to discuss.
> 
> SPLIT-UP INTERNET.XML

{snip}

> I propose that we have four XML files, all in ubuntu/internet/C:
> 
>  * internet.xml - the root page of the document, similar in concept to
> config-desktop.xml
>  * connecting.xml - documentation which covers *connecting* to networks
> and the Internet
>  * networking.xml - Internet and networking docs which *aren't* to do
> with connecting (e.g. using Samba)
>  * web-apps.xml - documentation on browsers, mail clients and so on

I'd like to understand better the proposal. Are you suggesting having
different topics on the front page of the help system, or just having
different categories under the main heading of "Internet"? If the
latter, I have no objections. If the former, I'd be very concerned about
increasing the number of topics on the front page in the absence of a
special justification to do so.

> BETTER DIAL-UP MODEM DOCS
> 
> The documentation for dial-up modem users isn't very good. We should
> assume that the user doesn't have an Internet connection, but the modem
> documentation depends on having a working Internet connection so that
> they can click links and wget scanModem!
> 
> Does anyone know how scanModem is licensed? I think that we should try
> to ship the script on the installation CD if possible.

No one will object to improving this section, if we can. Unfortunately,
it's really difficult - I looked at doing this in the last release
cycle, and found that the support for modems in Ubuntu is so bad and
that the instructions required are so dependent on individual modem
models that it's actually prohibitive to do anything like a proper job
on this.

The main problem with scanModem is that the script doesn't work properly
for many modems (including mine), and the developers who I've talked to
say that it's total crack.

The only thing I can suggest is to work with some of the developers who
might be able to improve modem support in Ubuntu and do a joint prong
attach - improving modem support and improving the documentation.
Matthew Garrett is the first person to contact about this, I think.

> NETWORK MANAGER
> 
> We barely mention NM in the docs at the moment, even though it's enabled
> by default.

We should certainly include information on how to use this feature, it's
the best way to connect to wireless networks, and will simplify the
documentation enormously.

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

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 252 bytes
Desc: OpenPGP digital signature
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20070730/033fd116/attachment.pgp>