SpecTbhDocs

Summary

This specification describes the needed sections and implementation into the current Kubuntu Topic Based Help documentation.

Rationale

As Kubuntu matures so does the documentation. At this point in time, the system documentation (installed with the release) lacks the necessary information for ATI and NVidia binary drivers, dial-up modems, wireless networking hardware, as well as other configurations. This documentation should answer the more popular questions, or better yet instruct the user how to fix or work with the most common topics.

These new additions will allow the user to get the answer to their questions locally without the need of an Internet connection. Also these additions will allow us to document properly what has been documented on many websites in various ways. There are more than 10 major sites that document ATI and NVidia, yet none of them are very clear for someone who is not used to the command line, nor do these sites document one solution for the various hardware releases clearly. Our goal is to bring the best solution for each environment locally and in one easy to access location.

Another addition would be to add an index.html file or index rather in the main /usr/share/doc/kde/HTML/$lang/kubuntu/ directory. This would make accessing the topic based help as easy as using Konqueror and typing in help:/kubuntu.

Use Cases

  • Bob connects to the Internet via his 56k dial-up modem, however the initial installation did not properly recognize nor configure his modem due to it being a software (Win) modem. Since Bob cannot connect to the Internet in order to find documentation to show him how to configure his modem and connection, wiki pages and PDF files are out of the question. Bob can easily go to KMenu -> Help, select Kubuntu System Documentation and locate the topic for his modems under Networking or Hardware.

  • Pedro leaves his house to go to the local cafe to use their Internet connection with his wireless device. When Pedro gets to the cafe he realizes his wireless connection does not work. Since Pedro cannot access the Internet for wiki pages and such, he wouldn't be able to properly configure his hardware. With these new implementations, Pedro would be able to access information for wireless hardware and configuration through KHelpCenter easily, or by typing help:/kubuntu/networking, and get his connection up and running (as long as he was carrying a CD or DVD with him).

  • Jason wants to configure his NVidia graphics card so he can use a composite window manger or play his favorite game. Jason goes to the many wikis and website that provide this information, but is unable to clearly decide which route he should go. Having the best route documented locally, or the recommended route, would save Jason the troubles of having a disfunctional X windows.

Scope

This specification covers feature specifications for the kubuntu-docs package for the 7.10 (Gutsy Gibbon) release.

Design

  • DocBook/XML

  • No Chapters! (refer to the TopicBasedHelp specification for more information)

  • ATI & NVidia documentation should document using the drivers provided in the repositories

  • Wireless hardware should be documented using the applications provided in the repositories
    • Seeing as someone may require wireless for an Internet connection, inform them properly that an Internet connection is needed in order to download a required application. Inform them of the options available via the CD and/or DVD.
  • Modems - utilize information from the Linmodems.org website. Need documentation that will work with the largest majority as possible. After speaking with the Linmodem group, it would be impossible to document fully every device available. Document hardware modems!

  • Utilize the KDE documentation style guide (http://l10n.kde.org/docs/styleguide/index.html)

    • Also refer to the Ubuntu styling guide which is out of date at this time

    • Confer with <ubuntu-doc AT lists DOT ubuntu DOT com> and the members on IRC in #ubuntu-doc

Implementation Plan

Implementation should start as soon as next week (first week of May 2007) in order to get a solid foundation internally to work with. A new pre-release of Kubuntu during the Gutsy development cycle will contain a new kubuntu-docs package every time. This will allow improved bug reporting from day one, and ease the translation time towards the end of the development cycle. Other changes besides those summarized in this specification will also be implemented. This will be done to close any bugs that may arise.

Implementation

Implementation of this specification should be seemless since the foundation has already been created with the 7.04 release.

Outstanding Issues

  • No issues at this time.

BoF agenda and discussion

BoF is not necessary unless other members from the Documentation Project are available. If there is a remote communication link like previous developer summits, I (RichardJohnson) will be open to discuss further, or via IRC.

CategorySpec

KubuntuDocs/Gutsy/SpecTbhDocs (last edited 2008-08-06 16:41:42 by localhost)