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

Mon Feb 27 23:37:23 UTC 2012

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?

Albert

> 
> > El Diumenge, 5 de febrer de 2012, a les 23:03:58, Burkhard Lück va 
escriure:
> > > Am Sonntag, 5. Februar 2012, 00:47:57 schrieb Albert Astals Cid:
> > > > Could you give a quick summary of what building blocks is for the
> > > > people that  haven't been following the discussion much?
> > > 
> > > The actual version of building blocks can be found in
> > > http://websvn.kde.org/branches/work/doc/buildingblocks/
> > > 
> > > Credits for the name and idea go to Chusslove
> > > (http://lists.kde.org/?l=kde- i18n-doc&m=123461844907311&w=2), for the
> > > work to T.C. Hollingsworth and various GoogleGoogle Code-In 2011
> > > participants.
> > > 
> > > Now we have:
> > > 
> > > * entities from kdelibs/kdoctools/customization/ (help-menu,
> > > install-intro, report-bugs, install-compile, update-doc etc) pulled into
> > > all application docbooks.
> > > Not processed by scripty, so translation teams are not automatically
> > > notified about changes/updates
> > > * lot of docs for task common to all KDE applications (shortcuts,
> > > toolbars, spellcheck, file dialog, common menu items etc) slightly
> > > different in many application docbooks.
> > > 
> > > With building blocks:
> > > * all common docs in one place
> > > * move as much as possible (all?) from kdelibs/kdoctools/customization
> > > into building blocks
> > > * in application docbooks sections about shortcuts, toolbars,
> > > spellcheck,
> > > file dialog, common menu items, help menu etc will be replaced with
> > > links
> > > to the relevant section in building blocks.
> > > 
> > > Benefits with building blocks:
> > > 
> > > * documentation team:
> > >   one central place to keep the common doc stuff up to date
> > >   not wasting time to keep similar docs spread over may docbooks up to
> > >   date,
> > > 
> > > but concentrate on application specific tasks and infos
> > > 
> > > * translation teams:
> > >   automatical notification via scripty about changes of entities now in
> > > 
> > > kdelibs only one translation of common tasks, not many but slightly
> > > different in several application docbooks
> > > 
> > > * users
> > > 
> > >   experienced kde user are not bored reading known infos over and and
> > >   over again in any docbook, they get only the application specific
> > >   infos
> > > 
> > > Migration procedure:
> > > 
> > > Copy of finished parts of buildingblocks should go into master
> > > immediately and should be backported to 4.8 as usual. Chapter/Section
> > > with info about getting the sources and build it has to be added asap,
> > > because in ~50 % of all application docbooks it is currently wrong due
> > > to splitted git repos (e. g. no kdeedu tarball any more)
> > > 
> > > In the meantime the doc team tries to improve and extend the building
> > > blocks in branches/work (visuell dictionary, a11y, application overview
> > > for common tasks, etc, etc) and copy to master/backport the parts ready
> > > to get in.
> > > 
> > > For translation teams the building blocks in stable should be kind of
> > > essential like the essentials for GUI.
> > > 
> > > If we have enough (what is enough here?) translated building blocks in
> > > stable, the doc team can start to replace every info in an application
> > > docbook which is in building blocks with a link. Of course first only in
> > > kde main modules, later on in extragear + playground.
> > > 
> > > Both systems have to coexist for at least a few years until all
> > > applications in kde git require a minimum kde version with the building
> > > blocks.
> > 
> > _______________________________________________
> > kde-doc-english mailing list
> > kde-doc-english at kde.org
> > https://mail.kde.org/mailman/listinfo/kde-doc-english