Progress is good for us but bad for documentation

[Frederik Schwarzer]

Hi everyone,

thank you for your input and sorry it took me a while to reply.

For now I have created a list of issues on gitlab to be reminded.
https://invent.kde.org/teams/documentation/sprints/-/issues

Some issues I started to investigate but was struck by kapidox_generate 
being broken on my local machine. This is now addressed and will 
hopefully be fixed soon. :)

Others like the KXmlGui ones I reply to here, I will play through at 
some point and look what I can do to fill some holes.

Feel free to add issues to the issues list as you stumble over them.

Cheers,
Frederik


On 6/14/21 2:00 PM, David Hurka wrote:
> Hi Frederik,
> 
> here is my report about a negative experience with existing documentation:
> 
>> So what to report? Documentation that ...
>> - [...]
>> - has holes in it. For example a tutorial where you suddenly think,
>>     you skipped an important step.
>> - you wish was there but you could not find it.
> 
> When I tried to understand KXmlGui an KParts (about 15 months ago?), I felt
> left alone from the documentation.
> 
> KXmlGui:
> 
> KXmlGui explains itself as user configurable main windows (toolbars,
> shortcuts), which should be enough for an introduction. But KXmlGui docs
> didn’t give me examples how to use it. Just creating a KXmlGui main window and
> putting a KXmlGuiClient in it didn’t work as easy as setting the main widget
> of a QMainWindow. My experiment application always crashed at startup.
> 
> Here I would expect some minimal working examples.
> 
> It also misses an introduction about merging multiple KXmlGuiClients to one
> user interface.
> 
> KParts:
> 
> KParts didn’t tell me what the whole framework is good for. After reading the
> documentation, I doubted that a KPart is anything more than a KXmlGuiClient
> with another name or even a QWidget with a list of actions. Why not just
> instantiate a QWidget derived object from a library, and put that QWidget in
> my main window?
> 
> Here I would expect an introduction why I should use KParts.
> 
> Only KReadOnlyPart and KReadWritePart made some sense for me. These were able
> to provide reading and writing files through KIO just through the openUrl()
> and saveAs() methods. And Konqueror can search for a KReadOnlyPart that allows
> to open a specific document type, and use this part through a common API.
> 
> Cheers, David
> 
>