[kde-doc-english] how to handle build instructions?

[Luigi Toscano]

Thomas Eschenbacher ha scritto:
> Luigi Toscano wrote:
>> [...]
>>> I also plan to add some section that tells how to get a translated
>>> version of the application, where to get the translations from, how to
>>> build them, and to handle this in packaging (I think I will offer a
>>> kwave-l10n package for this, which needs to be reflected in the
>>> documentation as well).
>>
>> I disagree with this. The docbook documentation is for end users, who usually 
>> finds the program already installed. This is also why we started removing the 
>> installation instruction (the appendix) from this documentation (see the last 
>> version of docbook templates into KDocTools).
>>
>> What you described is developer documentation, which could live in the usual 
>> internal README, and on the other side the steps you would describe are common 
>> among all other projects hosted on kde.org (so a page on one of the wikis).
> 
Hi, sorry for the delay, answers inline:

> That's an interesting point! Do you have some links to these "wikis"?
> I mean something that...
> 
> 1) clearly explains the way from a git repository or tarball
>    to an installable package
> 2) is describing how to get a translated GUI
> 3) includes a (translated) handbook, and
> 4) is available in different languages?

Yes, this kind of information should be available on techbase.kde.org.
In fact we used a special entity in docbooks which included a reference to the
installation instruction on the wiki (&install.intro.documentation; and
&install.compile.documentation;) but we are phasing them out slowly. Check
this review for some background:
https://git.reviewboard.kde.org/r/123850/

Unfortunately the wiki pages are not up-to-data right now (the starting point
is: https://techbase.kde.org/Getting_Started ) but there is a plan to update
the wikis in an upcoming sprint:
https://sprints.kde.org/sprint/291


> 
> If you can point me to an adequate replacement that I can link to from
> the homepage, then I can safely remove these sections from my handbook.
> 
> One point is that the handbook is currently also rendered as html and
> made available on the project's homepage (including translated
> versions!). This way the (translated) build instructions are available
> even when not having the package installed.

Right, but general installation details should be better not repeated around,
and the wikis allow translations.

Ciao
-- 
Luigi