[kde-doc-english] Building blocks ready to go into master?

[T.C. Hollingsworth]

On Mon, Feb 27, 2012 at 4:37 PM, Albert Astals Cid <aacid at kde.org> wrote:
> El Dilluns, 27 de febrer de 2012, a les 22:57:26, Burkhard Lück va escriure:
>> Am Sonntag, 26. Februar 2012, 23:23:23 schrieb Albert Astals Cid:
>> > Sorry for the top posting :-)
>> >
>> > One question about "Building blocks", i think you told me the idea was
>> > that
>> > "Building blocks" would be a separate manual, meaning that the Okular
>> > manual (using Okular as example here) would no longer have the information
>> > of how the "File" menu works, but instead if would have a link to the
>> > "Building blocks" manual that speaks of the "File" menu.
>> >
>> > Is this right or did I misunderstood you?
>>
>> Somehow you misunderstood me resp. the use case for the "Building blocks".
>>
>> Using the okular docs as example, there are some "File" menu items special
>> to Okular.
>> Of course these items (Import PostScript as PDF, Save As, Save Copy As,
>> Print Preview, Properties, Embedded Files, Export As etc.) will be in the
>> Okular docs.
>> And if there are other items in the Okular "File" menu with more infos as in
>> the current "Building blocks" documentation ("File → Open" for example) and
>> if these infos are valid for other applications as well, these docs will be
>> used to extend/update the building blocks documantation.
>>
>> A better example where the building blocks documentation will simply replace
>> application docs is the Help menu or Settings → Configure Shortcuts or
>> Settings → Configure Toolbars.
>> This documentation is shared and valid for nearly all other
>> KDE-Applications, so it makes no sense to have it in a lot of docbooks.
>
> I disagree, it makes sense from the point of view of being complete, i.e. I
> want the user to be able to understand all Okular menus just reading the
> Okular documentation. Will that be possible using "Building Blocks"? Or will
> he need to open a second documentation?

Well, for Kate/KWrite I probably won't drop the Settings menu, since
there's some katepart-specific stuff in there too and sending them to
buildingblocks for three entries is kind of silly IMHO.  Okular has a
bunch of it's own stuff in there too, so you'll probably want to do
the same.

I'll definitely just link to buildingblocks for the Help menu, though.
 IMHO, if users actually need to read the docs for the help menu they
would probably benefit greatly from a pointer to the other fundamental
stuff in buildingblocks anyway.

Also, we have shiny new documentation for Configure Shortcuts/Toolbars
and other comman dialogs.  Those aren't documented at all ATM, so
while you might want to keep short blurbs about those entries in the
Okular doc, linking to the buildingblocks section that actually
explains how to use them is a definite win.

-T.C.