Kubuntu Docs

[David Wonderly]

Recently there has been the beginnings of restructuring the Kubuntu Docs 
package.

A little background to start with.

For a while there has been a concern with the shipped Kubuntu Docs not being 
translated, not being up to date and being too much to maintain for the small 
team. 

On top of all of this, the learning curve to DocBook is something that people 
don't seem to want to do. I have been a fan of docbook for many years and I 
still think it is one of the best ways to write docs but, many people don't 
want to take the time to learn XML and the DocBook DTD. 

The other part of DocBook is very few of us who maintain the kubuntu-docs 
package actually know DocBook through and through, with other things in our 
lives, it has created a choke point for quite a while.

This is one of the many reasons we started looking at a new way to write and 
view the kubuntu-docs.

The primary doc work will be hosted on the Kubuntu Wiki. 
(https://wiki.kubuntu.org/Kubuntu/KubuntuDocs for now) and will be setup to 
look really nice on a wiki page. This will be an all inclusive docs run, with 
links to other projects that we ship documentation on. (KDE, LibreOffice etc.) 
This will help with limiting the amount of duplicated documentation. This has 
been something that has bothered me for quite a while. The amount of 
duplicated effort that goes into our docs.

So, we will have two sets of docs on line. There will be the all inclusive 
docs that I talked about above and a pure minimal set of docs to ship with the 
ISO.

A little about the theory of a smaller set of docs to ship.

The idea is someone new has installed Kubuntu for the first time. Now, while we 
do have some bit that is laid out like Windows (This is good because there is 
an instant familiarity with the layout) There will be a lot of people who are 
totally lost. Even the simplest tasks like connecting to the internet can 
because confusing to a new user.

So, we need to have something that explains a VERY brief use case on doing the 
simplest tasks. 

Connecting to a Wifi or LAN.
Brief overview of how to get around Kickoff.
Brief explanation of the Plasma Widgets.
Explaining that Rekonq is a web browser.
Explaining that Amarok is a Full feature music player.
Explaining what Dolphin is.
Explaining what LibreOffice is.
Explaining how to get more information once online.

That should be it.

This is very minimal, very easy to maintain and shouldn't really have to 
change too much from release to release. 

This is to ENSURE the highest quality for the docs that are shipped with the 
ISO with each release. This will also allow us to get the docs translated with 
more ease than before.

Now, as we know, the default install of Kubuntu has the plasma widget of 
Desktop Folder automatically on the desktop. If we were to have a "Need Help?" 
icon in there to open these brief docs, this would be a way to announce to new 
users there is a step by step help page.

Now, taking this basic docs that is shipped, I would argue and propose that 
this basic few pages remain in the DocBook DTD of XML, due to the nature of 
this, it should not change much, if at all, from release to release. This way 
we can ensure the highest quality and have to choke points will be good.

Back to the full online docs. 

I would envision this to be setup much like techbase.kde.org is setup. This 
would allow us to have a professional looking doc set online. It would look 
nice and it would allow us to put forward the best information, keep it up to 
date, fix typos and errors instantly and with the work in translating webpages 
on the fly, would fulfill that need as well.

tl;dr

Ideas for reworking the way Kubuntu approaches docs. Minimal docs shipped 
with the ISO, the rest online. 

Please note, this is an OPEN discussion. I am not trying to fully dictate how 
the Kubuntu Docs will move forward. I just believe that we need to move. 
Forward is as good as a direction as any.

Cheers!

David Wonderly
Darkwing on FreeNode IRC in #kubuntu-devel and #Kubuntu