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

[Burkhard Lück]

Am Dienstag, 23. September 2014, 19:53:09 schrieb 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.  :-)
> 
I am fine with merging the content of plasma handbook and fundamentals, but 
fail to see the benefits of this split.

>From a technical pov I agree with your proposal, documentation should be in 
the same repo as the corresponding code, e.g Toolbars/Shortcuts -> kxmlgui

But looking from a documentation readers pov all docbooks are only usable via 
the help ioslave, and the help ioslave is afaik only used and usable in 
khelpcenter and konqueror.

That means a user without khelpcenter or konquerer can not display any docbook 
help. So the repo with khelpcenter code is the my preferred location for this 
documentation.

Thanks

-- 
Burkhard Lück