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

[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?

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.