Change the document about helping Krusader, add other ways
Needs ReviewPublic

Authored by asensi on Aug 20 2019, 9:53 PM.

Details

Reviewers
yurchor
nmel
Group Reviewers
Krusader
Summary

When releasing the next version of Krusader, perhaps someone will wish to help and will look https://docs.kde.org/trunk5/en/extragear-utils/krusader/help_krusader.html. A reference to that page maybe would also be useful if it's included in the release message, so that new helpers know immediately where to start.

Some tasks can be added to https://docs.kde.org/trunk5/en/extragear-utils/krusader/help_krusader.html in order to free developers, so that they can have more time to e.g. improve Krusader's source code.

All of this can be talked about, as also the relation of the aforementioned page with https://krusader.org/get-involved/.

About the "freshmeat.net" and "linux-apps.com" links in the "Rate Krusader" section: the linked pages were not updated since too many years ago.

Diff Detail

Repository
R167 Krusader
Lint
Lint Skipped
Unit
Unit Tests Skipped
asensi created this revision.Aug 20 2019, 9:53 PM
Restricted Application added a project: Documentation. · View Herald TranscriptAug 20 2019, 9:53 PM
Restricted Application added a subscriber: kde-doc-english. · View Herald Transcript
asensi requested review of this revision.Aug 20 2019, 9:53 PM
pino added a subscriber: pino.Aug 21 2019, 5:03 AM

TBH I'd just add the instructions to https://krusader.org/get-involved/, and not to the user documentation.
Just like we do not add compilation/build instructions to documentations anymore, IMHO it makes sense to not add contribution instructions either: they are generally not related to "using the application", and thus the old documentation shipped with an old version would show outdated links. Some of the changes in this patch perfectly show this: imagine that users installing krusader in stable distros have outdated links to freshmeat and linux-apps in the documentation they read.

Hi, Pino!

In D23309#515717, @pino wrote:

TBH I'd just add the instructions to https://krusader.org/get-involved/, and not to the user documentation.

Yes, the "All of this can be talked about, as also the relation of the aforementioned page with https://krusader.org/get-involved/" sentence was about discussing that, thanks for expressing your opinion. Information must be updated. At this point, would you add some information (or modify it, etc.) about how people can help Krusader :-?

Note: There are some reasons why Krusader users have documentation available in their computers, maybe Yuri Chornoivan can give more information about it. Anyway, there are a lot of possibilities for a following discussion: "how can you help Krusader" information can be placed in https://krusader.org/get-involved/, in the local help files a link can point to https://krusader.org/get-involved/; or in https://krusader.org/get-involved/ a link can point to https://docs.kde.org/trunk5/en/extragear-utils/krusader/help_krusader.html, etc. There are advantages and disadvantages that can be talked about, and links are very useful to avoid duplicating information.

yurchor accepted this revision as: yurchor.Aug 21 2019, 6:39 AM
yurchor added a subscriber: yurchor.

Personally, I think that there will be no harm if we have as many ways to engage new developers as we can.

Sure, the idealistic thought that every user is a potential developer does not work, but it's free to invite people to take care of their software this way.

doc/help.docbook
47

Entity usage: e.g. -> ⪚

80

Same here.

This revision is now accepted and ready to land.Aug 21 2019, 6:39 AM
pino added a comment.Aug 21 2019, 7:17 AM

Note: There are some reasons why Krusader users have documentation available in their computers, maybe Yuri Chornoivan can give more information about it.

Sure, nobody is suggesting removing that.

Anyway, there are a lot of possibilities for a following discussion: "how can you help Krusader" information can be placed in https://krusader.org/get-involved/, in the local help files a link can point to https://krusader.org/get-involved/; or in https://krusader.org/get-involved/ a link can point to https://docs.kde.org/trunk5/en/extragear-utils/krusader/help_krusader.html, etc. There are advantages and disadvantages that can be talked about, and links are very useful to avoid duplicating information.

As I said, IMHO the best is to point the installed documentation to https://krusader.org/get-involved/. Getting involved into krusader IMHO is not something that depends on the krusader version, which is something the user documentation reflects.
Let's take an actual example: currently this documentation chapter mentions phabricator, which soon will be gitlab (where KDE is heading to). Now the user installs krusader from a stable distro (the latest Debian/Fedora/openSUSE/etc), then they read to use phabricator, and they try to reach it... which won't exist anymore.

To recap:

asensi marked 2 inline comments as done.Aug 21 2019, 9:29 PM
asensi added inline comments.
doc/help.docbook
47

OK :-)

asensi updated this revision to Diff 64253.Aug 21 2019, 9:30 PM
asensi marked an inline comment as done.

Changes that were suggested.

yurchor accepted this revision.Aug 22 2019, 4:36 AM

Yes, Pino is right on the general level. The only problem with https://krusader.org/get-involved/ is that it is even more conservative than our user docs (slowly updates, no translations, etc.). So I'd better leave the things as is. Just my 2 cents.

pino added a comment.Aug 22 2019, 4:47 AM

The only problem with https://krusader.org/get-involved/ is that it is even more conservative than our user docs

https://cgit.kde.org/websites/krusader-org.git/
Just open a review request for that repository (or commit directly), it is not complicated...

(no translations, etc.).

You need to known English to contribute anyway, almost all the tasks added by this patch require that. Hence I do not see how making them translatable helps anyway: even if the users read them in the translated documentation, as soon as they get to the "get involved" page the translation factor becomes useless.

So better be honest upfront: have only a small Help paragraph pointing to https://krusader.org/get-involved/, mentioning that the page is in English.

It seems that we need some thoughts from developers on how to proceed.

nmel added a subscriber: nmel.Aug 22 2019, 6:36 AM
In D23309#516339, @pino wrote:

The only problem with https://krusader.org/get-involved/ is that it is even more conservative than our user docs

https://cgit.kde.org/websites/krusader-org.git/
Just open a review request for that repository (or commit directly), it is not complicated...

Please always open a review! Committed and pushed changes are deployed directly to live site. People make mistakes, it's normal, and reviews reduce the likelihood of a mistake.

(no translations, etc.).

You need to known English to contribute anyway, almost all the tasks added by this patch require that. Hence I do not see how making them translatable helps anyway: even if the users read them in the translated documentation, as soon as they get to the "get involved" page the translation factor becomes useless.

So better be honest upfront: have only a small Help paragraph pointing to https://krusader.org/get-involved/, mentioning that the page is in English.

I agree with this point. If potential devs have problems with English and are curious enough, they'll use their favorite Page Translate service. It won't be ideal but at least it will be the most up-to-date translation.

In D23309#515743, @pino wrote:

As I said, IMHO the best is to point the installed documentation to https://krusader.org/get-involved/. Getting involved into krusader IMHO is not something that depends on the krusader version, which is something the user documentation reflects.
Let's take an actual example: currently this documentation chapter mentions phabricator, which soon will be gitlab (where KDE is heading to). Now the user installs krusader from a stable distro (the latest Debian/Fedora/openSUSE/etc), then they read to use phabricator, and they try to reach it... which won't exist anymore.

And I agree even more with this. I believe the majority of people just use what their distro suggests and this info will be outdated inevitably. Current dev affairs don't depend on the app version.

+1. Toni, what you propose is a good change, however I think we should direct our efforts on keeping the online page as much detailed and updated as possible. It will be great to have starting steps for each type of work (for example, want to do Bug Triaging - go to the specific bugzilla link showing the list of not triaged bugs and try to repro bugs one by one, and then post your comments in the bugs).

@yurchor, in any case, the changes to the docs shall be made only in master, since stable is in the doc-freeze mode, correct?

In D23309#516348, @nmel wrote:

@yurchor, in any case, the changes to the docs shall be made only in master, since stable is in the doc-freeze mode, correct?

Sure.

asensi updated this revision to Diff 64361.Aug 22 2019, 9:18 PM

I suppose that today you have received a "Invitation to participate in a survey" mail from Lydia Pintscher. It reminds of when she wrote in https://phabricator.kde.org/T9581 about Krusader on Windows and "have you thought about using this as an opportunity to recruit someone new? Maybe a blog post or mailing list post asking if there is someone with the will and knowledge to drive this forward?", which has something to do with the subject of the present code review.

About what Yuri wrote, if I have understood him correctly, it also has the advantage of not causing having a very long page and a very short one, but two balanced ones, therefore in this review I've added two paragraphs to the "get involved" page.

Now that we're at it, in https://krusader.org/get-involved/ there's a https://build.kde.org/job/Extragear/job/krusader/job/stable-kf5-qt5%20SUSEQt5.10/ broken link. That link has to be updated periodically but it ends up not being updated, therefore, is it a good idea to have this link there?

P.S.: Some steps still have to be done, like the ones that Nikita commented "It will be great to have starting steps for each type of work (for example, want to do Bug Triaging - go to the specific bugzilla link showing the list of not triaged bugs and try to repro bugs one by one, and then post your comments in the bugs)" or mentioning that a linked page is in English.

nmel requested changes to this revision.Sep 12 2019, 5:33 AM

This diff contains combined changes on two separate repositories. Phabricator will have a problem with this kind of change. Please split into two reviews. I'm ok with the content.

This revision now requires changes to proceed.Sep 12 2019, 5:33 AM
asensi added a comment.EditedOct 7 2019, 9:31 PM

This diff contains combined changes on two separate repositories. Phabricator will have a problem with this kind of change. Please split into two reviews. I'm ok with the content.

Both diff files were ready, the plan was doing two commits, and closing this code review manually in order to avoid the split of this code review, having two different discussions to look at, etc.

asensi updated this revision to Diff 67466.Oct 7 2019, 9:32 PM

The first part of the splitted code remains in this code review, and the second part is now in https://phabricator.kde.org/D24480 .