I've just started working with Drupal. First, let me thank Steven Peck (I think I have that right) for the the reorganization described at http://drupal.org/node/44233. I didn't see the docs before them, but I'm finding the overall structure clear, and usefully task-oriented. It's a far sight from WordPress's maze of twisty little passages, all alike, which caused me to give up there and hunt until I found Drupal.
Being a good citizen, I read the page "Commenting on the handbook pages" (at http://drupal.org/node/14345) before commenting, but that left me more confused. The problem is that it says a lot about what should not go into comments, but doesn't really say what should go into comments; it just hints a bit.
From my perspective, I can only be a new user of the documentation once, and only for a few weeks. After that, I (and any other new reader) start to internalize the quirks and forget the stumbling blocks. So it's best to get my reactions down as soon as possible. But I'm not really sure where such comments belong. At this stage, I can make observations about what doesn't work for me, what seems weird, and suggestions about what I might like to see, but I can't do the actual writing until I get more experience with Drupal. The sort of quick impressions I have are along the lines of:
- the redundant install instructions pages seem silly (the unformatted followed by the formatted)
- the "Drupal 4.x" links at the top of some pages confused me for a while. On the Installing multi-site page at http://drupal.org/node/43816, I thought they would be links to the multi-site instructions specific to those versions, but they're not. This is mostly a formatting problem.
- such and such page used some jargon that I had to figure out by hunting elsewhere
- such and such paragraph isn't well structured, or some sentence is confusing
- such and such page should be split into two, or such and such pages should be combined or linked
I've already created one issue, which was a minor, non-controversial typo. However, many of these are opinions, so it doesn't feel write to create issues for them. And I don't want to annoy or offend contributors with too many editorial comments (grammar, sentence structure, etc.); I can be very old school about writing. I just don't know whether these sorts of comments belong in the forums, in the issues, on the doc mailing list, or elsewhere.
Many thanks,
Gary
Comments
Comment #1
Amazon commentedGary, thanks for a being a first class new user. You comments are useful and actionable. Keep those comments and first impressions comming so that we can act on them. I'll work with you directly to get the changes you recommend in.
You can email me directly at kieran at civicspacelabs dot org
Comment #2
Amazon commentedHi Gary, I added these guidelines and valid comments.
Valid comments
* Comments that provide useful facts that should be included in the handbook page are welcome.
* Noting errors in the documentation or corrections to incomplete information are valid comments.
* Links to similar content in the handbook, or links to inconsistent content in the handbook are useful.
* Providing links to modules, blogs, relevant articles are valid comments.
* Links to forum posts with new information directly related to the handbook page are useful.
* Complete re-writes of the handbook page to include information in other comments are welcome.
* Content that should become a child page of this handbook page is valid content.
* Noting links that are now invalid is a useful comment.
* Indicating that the handbook page includes terminology which new users are unfamiliar with are valid comments.
* Suggestions improvements to parts of the handbook page to make it clearer for new users are valid comments.
* Recommended re-organizations and outlines of handbook pages or handbook sections are valid comments.
Comment #3
Gary Feldman commentedLooks good, thanks,
Gary