Re: Progress is good for us but bad for documentation
On Thursday, July 1, 2021 12:03:44 AM CEST Frederik Schwarzer wrote: > 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 > > [...] Cool, thanks for your efforts! :) Cheers, David
Re: Progress is good for us but bad for documentation
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
Re: Progress is good for us but bad for documentation
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
Re: Progress is good for us but bad for documentation
On Wednesday, 9 June 2021 01:20:23 CEST Frederik Schwarzer wrote: > I would like to ask you to report such documentation to me. We see the > topic come up here and there but it then sometimes sinks into oblivion > again because it was part of a merge request that has then been merged > or so. Here's a little example of docs and code getting mismatched, and layout issues. It's just something I spotted because today I'm chasing crash bugs in skanlite (the KDE scanner application, for e.g. flatbed scanners). A dependent library is libksane, which is sort-of-maybe-a-framework .. I decided to look on api.kde.org. [[ typing this up, btw, takes way more time than just going out and fixing the documentation issues I've spotted, but that wouldn't illustrate the kind of persistent doc-rot we face; it's also not especially about this one bit of software from the KDE community ]] KSane sources https://invent.kde.org/graphics/libksane KSane api docs https://api.kde.org/libksane/html/index.html ## README.md [[ visible on the api docs front page ]] - dependency information, not one of these matches what's in CMakeLists.txt - "CMake options" weirdly include the `D` which isn't part of the option name - where this could be markdown links, it isn't - formatting of bash command leaks into the documentation page ## KSaneIface - plenty of typos incl "Read, Grean, Blue" colors - (rather a personal bugbear) inconsistent start of docs, sometimes right after /** and sometimes on the next comment line - do we have any standard for indicating boolean return values? Seeing 'true' and 'false' (with single-tick quotes) as return values (and sometimes without the ticks) is .. could be better. It should be noted the API docs are pretty **good**, and that the docs-rot reaches the state of "could be better", not "is terribly wrong"; there's still non-zero effort to put into them and I don't know what's a good way to make everyone spring into action to polish them up. [ade] signature.asc Description: This is a digitally signed message part.
Re: Progress is good for us but bad for documentation
On Wednesday, 9 June 2021 01:20:23 CEST Frederik Schwarzer wrote: > I would like to ask you to report such documentation to me. We see the > topic come up here and there but it then sometimes sinks into oblivion > again because it was part of a merge request that has then been merged > or so. Here's a little example of docs and code getting mismatched, and layout issues. It's just something I spotted because today I'm chasing crash bugs in skanlite (the KDE scanner application, for e.g. flatbed scanners). A dependent library is libksane, which is sort-of-maybe-a-framework .. I decided to look on api.kde.org. [[ typing this up, btw, takes way more time than just going out and fixing the documentation issues I've spotted, but that wouldn't illustrate the kind of persistent doc-rot we face; it's also not especially about this one bit of software from the KDE community ]] KSane sources https://invent.kde.org/graphics/libksane KSane api docs https://api.kde.org/libksane/html/index.html ## README.md [[ visible on the api docs front page ]] - dependency information, not one of these matches what's in CMakeLists.txt - "CMake options" weirdly include the `D` which isn't part of the option name - where this could be markdown links, it isn't - formatting of bash command leaks into the documentation page ## KSaneIface - plenty of typos incl "Read, Grean, Blue" colors - (rather a personal bugbear) inconsistent start of docs, sometimes right after /** and sometimes on the next comment line - do we have any standard for indicating boolean return values? Seeing 'true' and 'false' (with single-tick quotes) as return values (and sometimes without the ticks) is .. could be better. It should be noted the API docs are pretty **good**, and that the docs-rot reaches the state of "could be better", not "is terribly wrong"; there's still non-zero effort to put into them and I don't know what's a good way to make everyone spring into action to polish them up. [ade] signature.asc Description: This is a digitally signed message part.
Re: Progress is good for us but bad for documentation
One thing the seems entirely missing is any documentation what so ever of craft's runtime confurable options. I'm talking things maintainers can do in their config scripts not the end-user config file which is self documented. On Wed, Jun 9, 2021, 1:27 PM Frederik Schwarzer wrote: > > > On 6/9/21 6:02 PM, Johannes Zarl-Zierl wrote: > > Hi, > > > > Am Mittwoch, 9. Juni 2021, 01:20:23 CEST schrieb Frederik Schwarzer: > >> I would like to ask you to report such documentation to me. We see the > >> topic come up here and there but it then sometimes sinks into oblivion > >> again because it was part of a merge request that has then been merged > >> or so. > >> [...] > >> So what to report? Documentation that ... > >> - explains outdated technology or concepts like KDE 4 or HAL. > >> - 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. > > > > Is this an effort with universal scope, or is there a limit? > > Obviously you are at least talking about the wikis. Are you also (at the > > current time) talking about other websites and/or application handbooks? > > It is meant as an open question. All answers welcome. Of course not > everything can be worked on now. But compiling a list of stuff to work > on will help pushing and coordinating the work. > > heers, > Frederik >
Re: Progress is good for us but bad for documentation
Hi, Am Mittwoch, 9. Juni 2021, 01:20:23 CEST schrieb Frederik Schwarzer: > I would like to ask you to report such documentation to me. We see the > topic come up here and there but it then sometimes sinks into oblivion > again because it was part of a merge request that has then been merged > or so. > [...] > So what to report? Documentation that ... > - explains outdated technology or concepts like KDE 4 or HAL. > - 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. Is this an effort with universal scope, or is there a limit? Obviously you are at least talking about the wikis. Are you also (at the current time) talking about other websites and/or application handbooks? Cheers, Johannes signature.asc Description: This is a digitally signed message part.
Re: Progress is good for us but bad for documentation
One thing the seems entirely missing is any documentation what so ever of craft's runtime confurable options. I'm talking things maintainers can do in their config scripts not the end-user config file which is self documented. On Wed, Jun 9, 2021, 1:27 PM Frederik Schwarzer wrote: > > > On 6/9/21 6:02 PM, Johannes Zarl-Zierl wrote: > > Hi, > > > > Am Mittwoch, 9. Juni 2021, 01:20:23 CEST schrieb Frederik Schwarzer: > >> I would like to ask you to report such documentation to me. We see the > >> topic come up here and there but it then sometimes sinks into oblivion > >> again because it was part of a merge request that has then been merged > >> or so. > >> [...] > >> So what to report? Documentation that ... > >> - explains outdated technology or concepts like KDE 4 or HAL. > >> - 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. > > > > Is this an effort with universal scope, or is there a limit? > > Obviously you are at least talking about the wikis. Are you also (at the > > current time) talking about other websites and/or application handbooks? > > It is meant as an open question. All answers welcome. Of course not > everything can be worked on now. But compiling a list of stuff to work > on will help pushing and coordinating the work. > > heers, > Frederik >
Re: Progress is good for us but bad for documentation
On 6/9/21 6:02 PM, Johannes Zarl-Zierl wrote: Hi, Am Mittwoch, 9. Juni 2021, 01:20:23 CEST schrieb Frederik Schwarzer: I would like to ask you to report such documentation to me. We see the topic come up here and there but it then sometimes sinks into oblivion again because it was part of a merge request that has then been merged or so. [...] So what to report? Documentation that ... - explains outdated technology or concepts like KDE 4 or HAL. - 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. Is this an effort with universal scope, or is there a limit? Obviously you are at least talking about the wikis. Are you also (at the current time) talking about other websites and/or application handbooks? It is meant as an open question. All answers welcome. Of course not everything can be worked on now. But compiling a list of stuff to work on will help pushing and coordinating the work. heers, Frederik
Re: Progress is good for us but bad for documentation
On 6/9/21 6:02 PM, Johannes Zarl-Zierl wrote: Hi, Am Mittwoch, 9. Juni 2021, 01:20:23 CEST schrieb Frederik Schwarzer: I would like to ask you to report such documentation to me. We see the topic come up here and there but it then sometimes sinks into oblivion again because it was part of a merge request that has then been merged or so. [...] So what to report? Documentation that ... - explains outdated technology or concepts like KDE 4 or HAL. - 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. Is this an effort with universal scope, or is there a limit? Obviously you are at least talking about the wikis. Are you also (at the current time) talking about other websites and/or application handbooks? It is meant as an open question. All answers welcome. Of course not everything can be worked on now. But compiling a list of stuff to work on will help pushing and coordinating the work. heers, Frederik
Re: Progress is good for us but bad for documentation
On 09/06/2021 18:02, Johannes Zarl-Zierl wrote: Hi, Am Mittwoch, 9. Juni 2021, 01:20:23 CEST schrieb Frederik Schwarzer: I would like to ask you to report such documentation to me. We see the topic come up here and there but it then sometimes sinks into oblivion again because it was part of a merge request that has then been merged or so. [...] So what to report? Documentation that ... - explains outdated technology or concepts like KDE 4 or HAL. - 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. Is this an effort with universal scope, or is there a limit? Obviously you are at least talking about the wikis. Are you also (at the current time) talking about other websites and/or application handbooks? Cheers, Johannes ... and API docs :) -- Ahmad Samir
Re: Progress is good for us but bad for documentation
Hi, Am Mittwoch, 9. Juni 2021, 01:20:23 CEST schrieb Frederik Schwarzer: > I would like to ask you to report such documentation to me. We see the > topic come up here and there but it then sometimes sinks into oblivion > again because it was part of a merge request that has then been merged > or so. > [...] > So what to report? Documentation that ... > - explains outdated technology or concepts like KDE 4 or HAL. > - 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. Is this an effort with universal scope, or is there a limit? Obviously you are at least talking about the wikis. Are you also (at the current time) talking about other websites and/or application handbooks? Cheers, Johannes signature.asc Description: This is a digitally signed message part.
Progress is good for us but bad for documentation
Hi, we are all making progress but the way to notice it can be painful. Looking at something you created years ago might make you cringe, but that's actually a good sign. It indicates, that you made progress. KDE is making progress as well. Here the indicator is outdated documentation. There is still quite some documentation from KDE 4 times where the technology documented already moved on to more modern times. And just as your résumé needs updating once in a while to reflect your newly acquired skills and references, documentation needs updating so it reflects the current state of KDE (as in software, places to communicate, go-to people for all the several parts of the projects, etc.). I would like to ask you to report such documentation to me. We see the topic come up here and there but it then sometimes sinks into oblivion again because it was part of a merge request that has then been merged or so. So to let me know, you can send me an email (on- or off-list) and I will create a ticket for it where further discussion can take place. Of course you could theoretically open a ticket yourself but we still need to find the best place for those topics. I will keep you posted on that one. :) So what to report? Documentation that ... - explains outdated technology or concepts like KDE 4 or HAL. - 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. Thanks a bunch. :) Cheers, Frederik
Progress is good for us but bad for documentation
Hi, we are all making progress but the way to notice it can be painful. Looking at something you created years ago might make you cringe, but that's actually a good sign. It indicates, that you made progress. KDE is making progress as well. Here the indicator is outdated documentation. There is still quite some documentation from KDE 4 times where the technology documented already moved on to more modern times. And just as your résumé needs updating once in a while to reflect your newly acquired skills and references, documentation needs updating so it reflects the current state of KDE (as in software, places to communicate, go-to people for all the several parts of the projects, etc.). I would like to ask you to report such documentation to me. We see the topic come up here and there but it then sometimes sinks into oblivion again because it was part of a merge request that has then been merged or so. So to let me know, you can send me an email (on- or off-list) and I will create a ticket for it where further discussion can take place. Of course you could theoretically open a ticket yourself but we still need to find the best place for those topics. I will keep you posted on that one. :) So what to report? Documentation that ... - explains outdated technology or concepts like KDE 4 or HAL. - 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. Thanks a bunch. :) Cheers, Frederik
