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

[Burkhard Lück]

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.

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


-- 
Burkhard Lück