[kde-doc-english] Splitting fundamentals [was: Review Request 116038: replace old included sections with links to fundamentals]

[T.C. Hollingsworth]

On Tue, Sep 16, 2014 at 11:20 AM, Luigi Toscano
<luigi.toscano at tiscali.it> wrote:
> Moreover, the contents of Fundamentals talks about both components and behaviors which are provided by different sources: Qt, various frameworks or directly Plasma. That's why I'm asking about rethinking and splitting fundamentals. Some sections should be moved down (some even here in KDocTools). But I really need help from you who wrote it for this.

Let's rethink it then.  :-)

Currently we have two manuals that provide a basic introduction to our
applications and workspaces.  There's Fundamentals, which covers basic
stuff like widgets, file dialogs, installation, etc. and is intended
to be useful for people using Plasma as well as other platforms.  And
there's the Plasma handbook, which just covers the desktop shell.

People not using KDE should really refer to their desktop's
documentation for much of that sort of stuff, because e.g. KDE
applications running in GNOME will be rendered with GTK and get GTK
file dialogs, so that part of fundamentals is useless to them already.
(Not to mention the type of person who really runs GNOME, and runs KDE
applications on top of it, is really not the type of person who is
going to read documentation like Fundamentals anyway.  ;-)  And, IMHO
people using KDE shouldn't have to look between two manuals for stuff
implemented on the library side vs. stuff implemented in the desktop
shell, because most of them really don't understand/care about this
difference.

For these reasons, I really don't think the fundamentals/plasma split
is really that useful to our users.  So IMHO we should do away with
it.

Let's split off unique KDE Frameworks features like Custom Shortcuts
off into their own little DocBook <article>s shipped along with the
framework, so any application depending on such frameworks can safely
and easily link to the documentation for using those features.  The
remainder should be merged with the existing Plasma handbook that
covers solely the desktop shell into one grand unified Plasma Handbook
that covers everything you need to know to use Plasma the Workspace.

Fundamentals would be split as follows:

1. Introduction -> N/A (new guides will get new ones)
2. Installing the KDE Software Collection -> Plasma
3. Finding Your Way Around -> Plasma
        A Visual Dictionary
        Common Menus
        Common Keyboard Shortcuts
4. Common Tasks
        Navigating Documents -> Plasma
        Opening and Saving Files -> Plasma
        Check Spelling -> sonnet*
        Find and Replace -> ktextwidgets
        Choosing Fonts -> kwidgetsaddons*
        Choosing Colors -> Plasma (this is done with pure Qt in KF5)
5. Customizing KDE Software
        Customizing Toolbars -> kxmlgui
        Using and Customizing Shortcuts -> kxmlgui
6. Credits and License -> eveywhere ;-)

*These are Tier 1 Frameworks and cannot depend on KDocTools.  So we'd
either need to knock them down or figure out something else to do with
their documentation (ship them in KDocTools?).  :-(

Comments/suggestions/criticism welcome as always.  :-)

-T.C.