Improve the documentation

[Moritz Bunkus]

This ticket was motivated by issue #10765 in which you basically told me to RTFM better. I did RTFM, however, there are several things that I think can be improved in order to enable users to be able to help themselves better without bothering you. They're supposed to make both your and our lives easier, so please don't perceive them as rants. I honestly am grateful for the work you've put into this pluing. It is quite impressive.

Feel free to ignore one or all of these points.

My main point of entry is the plugin's wiki page (probably for most users).

First point:

This is acct_mgr-0.4, while we've got maintenance release acct_mgr-0.4.2 already, see changelog. Only I've not synced the 0.11 branch yet, sorry. Anyway, go to the tags branch for the latest stable release, please.

The main page doesn't give you any clue where to download specific tags. The news entry on the right side doesn't include a download link. The "Release status, downloads and links" section doesn't contain that information either. It strongly suggests to download the 0.11 tree from Subversion by using bold letters. Nowhere is mentioned that the stable branch might lack behind the actual releases.

So only users with knowledge about Subversion (where do I find the tags, standard trunk/tags/branches layout etc) and intimate knowledge about your development process (development happens in trunk, releases are not always synced back to the stable branch 0.11, there are tags for the releases) have a change of actually finding that release.

Second point:

I've been a user since before 0.4. 0.4 introduced quite a few changes that were required in order to get an upgraded installation working again. Unfortunately the wiki doesn't include any upgrade instructions at all. The main page only includes the words "update" or "upgrade" in a single footnote.

The source tree includes the important file README.update. It does list what has changed, which is good. However, the wiki page doesn't mention the existence of such an external update documentation at all, making it very hard to find for the user. I've been bitten by this when I upgraded and spent a few hours reading over the wiki page time and again before figuring out there was an update file as well.

Third point:

Btw, did you notice the fat red disclaimer on how to use this ticket system when you entered this ticket? I'd appreciate, if you'd follow advice given there to try the mailing list for local installation and configuration issues first.

The wiki page contains a section "Bugs/Feature Requests". It does not list the information that there is a mailing list or an IRC channel which users should hit first, if at all possible. It only links to the bug tracker, which then prints that single line inside a large red block warning about using the correct component. This makes it easy to overlook the hint about the other places people might get help.

At the same time is not always clear to a user if a problem is with his setup or with the plugin himself. Maybe he should always ask the mailing list first in such a case, but then again having the module throw up due to a null pointer reference (C++ programmer lingo, sorry) can always be considered a programming error and therefore a bug.

Fourth point:

True. But did you care to read about the current, modularized registration yet? See AccountManagerPlugin/RegistrationInspector#ModularRegistrationChecks for details, that will certainly explain most of your observation.

I did read it, but I overlooked the fact that I hadn't included the registration for the email verification module. That was obviously my own mistake. However, I also think that this can be improved:

1. There is no single page which lists all of the possible components and all of the possible options for this pluign. The plugin has become quite huge with a lot of optional configuration, configuration that even changed considerably between 0.3.2 and 0.4. It would be easier for users if they had a single place where they could check whether or not their configuration was missing an important option. At the moment they have to scan over seven separate wiki pages.

2. The README.update file only includes a diff of the required changes between 0.3.2 and 0.4. While being easy to read for computers it is not as easy to read for humans, especially if lines alter between adding and removing things as README.update does. It happens quite easily that the human eye takes an - for a + and the other way around. Reordering the lines to include all removals before all the insertions would be one way to do it. Not using diff and creating two separate paragraphs labeled e.g. "Old:" and "New:" would probably achieve the same. This is where I went wrong; I had email verification enabled before moving to Trac 1.0 and AccountManagerPlugin 0.4, but I must have made the mistake back then when I didn't rename that one registration entry correctly.

[Steffen Hoffmann]

Replying to mbunkus:

This ticket was motivated by issue #10765 ...

Feel free to ignore one or all of these points.

I won't.

My main point of entry is the plugin's wiki page (probably for most users).

First point:

This is acct_mgr-0.4, while we've got maintenance release acct_mgr-0.4.2 already, see changelog. Only I've not synced the 0.11 branch yet, sorry. Anyway, go to the tags branch for the latest stable release, please.

The main page doesn't give you any clue where to download specific tags. The news entry on the right side doesn't include a download link. The "Release status, downloads and links" section doesn't contain that information either. It strongly suggests to download the 0.11 tree from Subversion by using bold letters. Nowhere is mentioned that the stable branch might lack behind the actual releases. So only users with knowledge about Subversion (where do I find the tags, standard trunk/tags/branches layout etc) and intimate knowledge about your development process (development happens in trunk, releases are not always synced back to the stable branch 0.11, there are tags for the releases) have a change of actually finding that release.

The lag has been my fault, partly due to being busy with updating the resource on PyPi, about 3:30 am, and forgetting about the final sync to the branch.

[Steffen Hoffmann]

(In [12517]) AccountManagerPlugin: Sync 0.11 branch to current stable release acct_mgr-0.4.2, refs #10769.

This was meant to follow immediately after [12484]. Sorry for the delay.

[Steffen Hoffmann]

Replying to mbunkus:

First point:

This is acct_mgr-0.4, while we've got maintenance release acct_mgr-0.4.2 already, see changelog. Only I've not synced the 0.11 branch yet, sorry. Anyway, go to the tags branch for the latest stable release, please.

The main page doesn't give you any clue where to download specific tags. The news entry on the right side doesn't include a download link. The "Release status, downloads and links" section doesn't contain that information either. It strongly suggests to download the 0.11 tree from Subversion by using bold letters. Nowhere is mentioned that the stable branch might lack behind the actual releases.

So only users with knowledge about Subversion (where do I find the tags, standard trunk/tags/branches layout etc) and intimate knowledge about your development process (development happens in trunk, releases are not always synced back to the stable branch 0.11, there are tags for the releases) have a change of actually finding that release.

Now tags branch is linked from the Download section of the main plugin page (revision 150).

Second point:

I've been a user since before 0.4. 0.4 introduced quite a few changes that were required in order to get an upgraded installation working again. Unfortunately the wiki doesn't include any upgrade instructions at all. The main page only includes the words "update" or "upgrade" in a single footnote.

The source tree includes the important file README.update. It does list what has changed, which is good. However, the wiki page doesn't mention the existence of such an external update documentation at all, making it very hard to find for the user. I've been bitten by this when I upgraded and spent a few hours reading over the wiki page time and again before figuring out there was an update file as well.

Now this important file is linked from the Download section of the main plugin page (revision 149) as well.

Thanks for making clear, that this is important to mention explicitly.

[Steffen Hoffmann]

Replying to mbunkus:

Third point:

Btw, did you notice the fat red disclaimer on how to use this ticket system when you entered this ticket? I'd appreciate, if you'd follow advice given there to try the mailing list for local installation and configuration issues first.

The wiki page contains a section "Bugs/Feature Requests". It does not list the information that there is a mailing list or an IRC channel which users should hit first, if at all possible. It only links to the bug tracker, which then prints that single line inside a large red block warning about using the correct component. This makes it easy to overlook the hint about the other places people might get help.

At the same time is not always clear to a user if a problem is with his setup or with the plugin himself. Maybe he should always ask the mailing list first in such a case, but then again having the module throw up due to a null pointer reference (C++ programmer lingo, sorry) can always be considered a programming error and therefore a bug.

Point taken. And you've been further proven right about the claimed documentation issues by several edits to the wiki documentation as noted before.

Btw, if you're that confident about such issues and solutions, its perfectly valid to do it yourself. Trac-hacks.org documentation is a Wiki after all.

Fourth point:

True. But did you care to read about the current, modularized registration yet? See AccountManagerPlugin/RegistrationInspector#ModularRegistrationChecks for details, that will certainly explain most of your observation.

I did read it, but I overlooked the fact that I hadn't included the registration for the email verification module. That was obviously my own mistake. However, I also think that this can be improved:

Pretty much possible, but bear with all developers here, that do it mostly in their spare time. I assure you, that hours of time already went into maintaining the documentation, not only upstream development.

1. There is no single page which lists all of the possible components and all of the possible options for this pluign. The plugin has become quite huge with a lot of optional configuration, configuration that even changed considerably between 0.3.2 and 0.4. It would be easier for users if they had a single place where they could check whether or not their configuration was missing an important option. At the moment they have to scan over seven separate wiki pages.

Once it was, and IMHO it was a true mess, just because there are so many components and options. With that mega-page in sight I had to worry, if I could really handle installation and configuration of this plugin - quite distracting. These days I consider especially the cookbook page the most complete reference, if you're looking for ideas and solutions.

2. The README.update file only includes a diff of the required changes between 0.3.2 and 0.4. While being easy to read for computers it is not as easy to read for humans, especially if lines alter between adding and removing things as README.update does. It happens quite easily that the human eye takes an - for a + and the other way around. Reordering the lines to include all removals before all the insertions would be one way to do it. Not using diff and creating two separate paragraphs labeled e.g. "Old:" and "New:" would probably achieve the same.

Hm, I included the diff representation for being a rather clear and compact form. But you're right, that I should have preserved usual groups of removed and added lines, not inventing another diff style. I'm just looking into it and will try to make it a bit clearer.

This is where I went wrong; I had email verification enabled before moving to Trac 1.0 and AccountManagerPlugin 0.4, but I must have made the mistake back then when I didn't rename that one registration entry correctly.

I consider this ticket as mostly resolved by now. But I will continue to care for your reasoning when proceeding with other issues, that should provide additional solutions to this topic, i.e. #8930. And that's certainly not a trivial task.

[Steffen Hoffmann]

(In [12530]) AccountManagerPlugin: Enhance readability of update notices by removing diff-style configuration hints, refs #10769.

[Steffen Hoffmann]

(In [12531]) AccountManagerPlugin: Some changes missing from [12530], refs #10769.

[Steffen Hoffmann]

(In [12543]) AccountManagerPlugin: Supply contrib script file, that I missed in [12517], refs #10769.