Improving documentation

Why so many different places for (user) documentation?
Ignoring the developer wiki and the deprecated techbase there is:

userbase.kde.org
community.kde.org
docs.kde.org

I guess community is for contributors, while docs and userbase is for user documentation?
Does there really need to be two wikis? Couldn’t the userbase wiki point to userbase.kde.org/Spectacle/Get_involved* (or something like that) instead of having two wikis?
How to avoid duplication with userbase and docs?

Handling different different versions / Operating systems
Looking at the recent Spectacle rework:
Some Distris get rework faster, some maybe still at the old version? Any idea how properly document different versions of the same program?

Also for example KDE Connect looks differently on Windows. Not sure its because the Windows version is older or it just has a different interface. How to handle that? Make a separate page or add a List item that says

  • Windows

Contributing
@Herzenschein please advise:

I am aware of Get Involved/documentation - KDE Community Wiki

It says:

The contribution model works like so: you add the content first, and then someone else can review it. If you want to discuss an addition that was made or will be made, you can use that wiki page’s Discussion section.

Does it really work like that? Can I just change a page and the changes don’t go live untlil someone approves it? Or should I use the Discussion Page? I am neither a native english speaker nor experienced with wikis, so I would my like that my changes would be approved instead of me changing the page directly

3 Likes

As far as I know, the userbase wiki is not really maintained anymore as it’s much easier to maintain the docbook or it’s stuff that should really belong on community.kde.org. There’s no talk about shutting it down yet as far as I know, because there’s still a wealth of information on there that hasn’t been moved yet (and who knows how many links).

Yes, via the local help function which should contain the relevant help for the version of Spectacle you have installed. I don’t think we serve different versions on doc.kde.org, only the latest. I’m not sure what we should do about platform differences though, although it could just be another section.

Anyone with a KDE account is free to edit the wikis to their pleasure, but also remember that also means any other user can undo bad edits too. There are a few wiki pages off-limits to regular editors (like the markdown help pages) but those are really the only limitations in place. If you feel like a change might be controversial, you can try bringing it up in #kde-www (or use a user draft page)

2 Likes

Maybe the more accurate way to say it would be:

“The contribution model [for the wikis] works like so: you add the content first, and then someone else may review it.”

If you change a page and save, it immediately goes live. The wikis don’t really have a review process before the changes go live.

After that, there’s no actual guarantee that your wiki changes will be reviewed by someone. The likelihood of that happening really depends on how popular the page is, or how many people are following it.

If you really want a review process, you can:

  • Write in the Discussion page of the wiki page you want to change, then wait for someone else to comment on it.

  • Comment about it in the kde-www group that redstrate mentioned above.

  • Make an issue in the Wiki Issues List on Invent.

In all cases you can sort of “promote” the changes you want to do by sharing them with people that would be interested in your changes.

4 Likes