Improve the documentation
|Reported by:||Moritz Bunkus||Owned by:||Steffen Hoffmann|
|Cc:||Ryan J Ollos||Trac Release:|
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).
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.
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.
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.
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:
- 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.
- 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.
Change History (7)
comment:4 Changed 4 years ago by
|Cc:||Ryan J Ollos added; anonymous removed|
|Status:||new → closed|