Progress is good for us but bad for documentation

[David Hurka]

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