kubuntu-devel Digest, Vol 101, Issue 23

[Aaron Honeycutt]

> Message: 1
> Date: Wed, 22 May 2013 19:51:25 -0400
> From: David Wonderly <david.wonderly at kubuntu.org>
> To: Kubuntu Devel <kubuntu-devel at lists.ubuntu.com>
> Subject: Kubuntu Docs
> Message-ID: <1603831.4UhgvXWkKm at promethues>
> Content-Type: text/plain; charset="us-ascii"
> 
> 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

So the wiki is the main work and then the that work is moved to the iso?

-- 
Sent from KMail on Kubuntu 13.04