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

[Albert Astals Cid]

El Dimarts, 28 de febrer de 2012, a les 21:14:06, T.C. Hollingsworth va 
escriure:
> 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.

To be honest i'm still not sure of how it works (yes i can be that difficult 
sometimes :D). Do we have a document that uses BuildingBlocks already? That'd 
be the easy way for me to understand it :-)

Cheers,
  Albert

> 
> -T.C.
> _______________________________________________
> kde-doc-english mailing list
> kde-doc-english at kde.org
> https://mail.kde.org/mailman/listinfo/kde-doc-english