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
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
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
