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

[Burkhard Lück]

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.

-- 
Burkhard Lück
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.kde.org/pipermail/kde-doc-english/attachments/20120205/eee67941/attachment.html>