Improving the Internet docs

[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

First, I'll try to justify why I'd like 'Connecting to the Internet' and
'Internet applications' to be separate:

 * Less crowded navigation sidebar in Yelp -> easier to find docs
 * Easier to maintain (internet.xml is currently 1032 lines long and
will get bigger in the near future)
 * 'Connecting' is about system administration tasks, 'Internet
Applications' is more about per-user stuff
 * We can use a more useful 'home page' for the 'Connecting' topic,
rather than just listing everything that's in the category

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

What the user sees is determined by how we write the new internet.xml,
and doesn't necessarily have to follow how the actual files are
organised. We can link to the GNOME docs from internet.xml too.

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.

There is a lot of modem-specific documentation on the wiki too. I've
converted some of it into basic, first-draft DocBook form (see
modem-chipsets.xml in the attached tarball), which we could ship on the
CD as well.

NETWORK MANAGER

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

I've attached a tarball with some rough ideas on how we could arrange
the 'Connecting' docs. Please take a look at them and let me know if you
think there's anything that we can use in the system docs.

Thanks,

Phil

-- 
Phil Bull
http://www.launchpad.net/people/philbull
-------------- next part --------------
A non-text attachment was scrubbed...
Name: internet-ideas.tar.gz
Type: application/x-compressed-tar
Size: 18101 bytes
Desc: not available
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20070729/44ecbf54/attachment.bin>