Do you know about https://invent.kde.org/documentation/develop-kde-org/-/tree/master/content (https://develop.kde.org/docs)? It's git based and me and others put quite some work into it ;)

But this is only about the technical documentation unfortunately, for the user documentation we still ue docbook XML files

@ognarb I had no idea this existed. Will take a look.

Improving the documentation is a good idea, but please consider there are two types of documentation:

• developer documentation
• user facing documentation (application manuals)

It seems your proposal is focusing on the first point, and in that case develop.kde.org is ready.

The user documentation instead should live inside the repositories. That doesn't prevent the existence of tooling to extract them and publish them, but there are clear advantage in the documentation living with the code, first of all by allowing them to be updated *and* branched at the same time. In some cases some manuals have been even created in their own repositories (krita) and having them put back in a single repository is just not going to get any benefit.

I had no idea, develop.kde.org already existed. My goal is already half done. Kind of.

While develop.kde.org website exists. It is kind of unmaintained I think. There are a lot of bug reports in it's gitlab repo but most of them are completely unanswered and also there are tons of broken links in the page from what I have seen. Aside from that build instruction of 99% of KDE apps is lacking. It is really difficult to even find a right way to setup development on your machine.

I was trying to build discover for a small UI change but the discover page don't even have a readme file for build instruction or anything. And discover is one of the most active repo in KDE. It doesn't even need to have complete build instruction but at the very least each and every repo must have a readme file linking to documentation somewhere else.

Documentation is severely lacking in KDE. It is almost impossible to do anything if you are new and want to contribute. The barrier is too high to even fix a simple UI bug in a program.

I think this goal should also include stuff about improving the existing user and technical documentation, like making it more complete, up to date, centralized, and easier to understand. The user documentation might also benefit from being in one place instead of either being in the Help Center, the UserBase wiki, the Community wiki, or its own website (like Krita and Kdenlive).
There is also still a lot of outdated technical documentation on TechBase that should be updated and moved to develop.kde.org. Most of the tutorials on there have messages saying that it's outdated and that there might be wrong information.

I think improving documentation would be a great goal.

As others have said, there are multiple audiences for documentation: users and developers, at a high level, but they could probably be categorized with more granularity, e.g. contributors and distribution packagers have distinct needs. I think documentation for all audiences would benefit from sustained attention, and I hope this goal can cover all of them.

To refine this proposal, I'd suggest focusing less on specific implementation technologies and more on what needs to be done—the sorts of things @logicalwillow mentioned. It might also be useful to look for some KDE projects that are doing particular things well in their documentation, so we can apply their good ideas to other KDE projects.

Notes from refinement session:

The proposal should reflect the new info that was raised in the comments, i.e. keep only the stuff about user documentation and how to elevate it to be "kick-ass". Remove the already solved parts. Perhaps focus a bit more about the problem that is left, and not try to figure out the exact solution right now.

The voting starts in a week, if you plan to update the proposal it is best to do it soon.

As the author did not act on the comments here, I will not move this proposal to the voting stage.

It's a shame, this is an important and actionable goal proposal. Is anyone interested in taking it over? Or is @Nowshed still around?

I was extremely busy with my professional life. Let me see what I can do now.

As other users have mentioned, the solved part is not actually solved. The main git based documentation is kind of stalled.

In T15621#280077, @Nowshed wrote:

As other users have mentioned, the solved part is not actually solved. The main git based documentation is kind of stalled.

But it was pointed out that the main git repository for developer documentation is already implemented, and the single git repository for user documentation is going to introduce more problems (because user documentation follows the program, and when it does not it's more difficult to handle).
The presentation of all the documentation (user and developer) can be unified, of course.

The proposal does not include any of the feedback. As it is, I don't think it can be voted.

I am adding some additional steps that I understood from the feedback. Not being a software developer is a huge disadvantage for me, but I wanted to start the discussion.

My feedback on the state of documentation in KDE:

Developer documentation

• Pretty good state already with https://develop.kde.org/docs
• Still, some kde4 tutorials need to be updated and migrated to there
• API documentation for C++ project is fine. For QML project it could be better but it's already better than before

User documentation

• Lot of work needed
• Need an update of design of the website docs.kde.org (I made multiple attempts in the past)
• Ideally, we should long term move away from docbooks (XML)
  • in the short term probably be good to add rst, ascidoc or/and md support to the website in addition to docbooks to make the transition easier

In both cases, it would be good to streamline the process of writing API doc/user doc when implementing new features or updating them. This is something quite related to the goal of @ngraham T15627

I agree with Carl's feedback - just note that "add rst" or other formats is not so straightforward as it may seems.

Regardless on the format used, if people don't write documentation when implementing features, any change would be useless.

About this proposal, it still points out the centralization of the sources as the solution, and I don't think this is the way to go as already mentioned.

Centralization of documentation should definitely solve a lot of problem. About User documentation I do agree that every app are different but core KDE development tools or any kind of development documentation/tutorial should be centralized. But even in case of User documentation there should be proper guidelines and APIs to organize all the documentation from KDE applications.

So I think all the developer documentation should be centralized at one repo but user documentation for the apps can be separate and kept in their own repo but they all must follow certain guidelines so that it would be consistent and people would know what to look for while going through it.

I'm happy that the discussion has come back, but sadly the proposal has missed the deadline to be included in the voting.
Of course, feel free to continue using the ticket for discussing the ideas mentioned in the proposal.