Kubuntu Docs

[Valorie Zimmerman]

Comments in-line below.

On Thu, May 23, 2013 at 1:58 PM, Jonathan Jesse <jjesse at gmail.com> wrote:
> One of the things I've long argued for is maintaining a local copy of the
> documentation.  We have to remember that not everyone has access to the
> internet and especially for things like setting up networking often times
> you won't have LAN access let alone Internet access to look things up.
>
> I think we do a tremendous disservice if we don't ship some form of
> documentation on the CD to the end users.
>
> Jonathan

Yes, it was unfortunate that we couldn't do that last cycle. However,
with the plans in work, the basic docs we'll include on the DVD (no CD
anymore) will be high quality, and *translated.* That to me, is huge,
and important.

> On Wed, May 22, 2013 at 7:51 PM, David Wonderly <david.wonderly at kubuntu.org>
> wrote:
>>
>> 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.

YES.

>> 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.

Excellent, IMO.

>> 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.

David, where to you propose working on these mini-docs?

>> 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

Thanks to you and jjesse for keeping up the docs for so many years,
and for Aaron (ahoneybun) for bringing his fresh enthusiasm to the
effort. Since we've started, I've seen a few others express interest.

David (Darkwing) is planning to open a Youtube channel for our Kubuntu
docs discussions, which might bring a few more interested people our
way. So speak up here or in IRC, and get onboard!

All the best,

Valorie
-- 
http://about.me/valoriez