I just finished updating http://drupal.org/upgrade this page just basically explains what a update / upgrade is, and links to other pages. I then found http://drupal.org/node/548922 which is very similar. I'm not sure if /upgrade is now complete or still needs work. How does someone know if it's complete? I personally think the links off of it are not in the best order or work quite right but I didn't know what the focus or intent of the page or links were. Personally I'd like to see the text of the update.txt posted. Why make someone open that file?
One of my personal issues with Drupal documentation is you have to read and read and read to find simple information. I think we need to keep aware of that, and link to more information while giving the basics with links to all the details. I also edited http://drupal.org/handbook/modules/update again, read read read and can't find the simple step of where it's located or how you can edit it. It also seems like stuff is repeated and repeated, hence my edits to the page, and links to the details. Then I find #548992 and wonder if what I just did is now being repeated again.
Also why is there a terminology page AND a Acronyms and expressions used on Drupal.org, you are making people go to two place to figure out what someone is saying, again more work for the reader. People just want answers, they don't want to work so hard to find them.
I'm not complaining at the documentation team :) you guys have worked hard, and I am willing to help when and where I can. I'm just bring up what imho is a real road block for people adapting Drupal. I'm a tech person, and live on the web, and I have issues finding something that should be easy, and end up frustrated and just leaving. Someone not a tech or webbie, is lost here, and that is a shame, and I'd like to do what I can to change that.
Comments
Hi Shari - So a couple
Hi Shari -
So a couple different things here:
Upgrade guide mainpage
Though http://drupal.org/upgrade has a bit more information, I find http://drupal.org/node/548922 clearer, which I believe it is because it is intended to actually replace the current /updgrade page when D7 is released, so docs team members have been working more actively on fixing up the D7 verision. (The 6 >7 upgrade guide becomes the main upgrade guide.)
Any work you're doing on the upgrade guide should really be done on the D7 version, and then noted on the Issue http://drupal.org/node/536854 (rather than here on the group) so that others can review your changes or give feedback.
I'm not sure how http://drupal.org/node/548992 is related - can you clarify?
Update module
"...read read read and can't find the simple step of where it's located or how you can edit it" -- where you can edit what? The module settings?
For now, I've reverted your changes on http://drupal.org/handbook/modules/update, as that page is considered up to date/complete for D7, and the changes weren't really coherent with the style guide formatting. Your changes are still saved in the page's revisions though. http://drupal.org/node/178772/revisions If you can describe what your thoughts were inserting the admin paths, maybe they can be added into the page in a more integrated way (as it's not very easy to follow when the page paths are in between paragraphs). Please do post on the issue for D7 core module pages to follow up on this: http://drupal.org/node/674474
Terminology/Acronyms
"Also why is there a terminology page AND a Acronyms and expressions used on Drupal.org, you are making people go to two place to figure out what someone is saying, again more work for the reader. People just want answers, they don't want to work so hard to find them."
Can you file an issue regarding this in the docs queue with some more information and links? Someone could have a better look at it then. But generally, we don't have Glossary module or anything to get definitions directly on a page, so I would imagine people have built and maintained some lists of commonly used technical terms for reference. It could be that they haven't been reviewed in a while.
General
If you can actually file issues regarding any problems or suggestions of changes, that would help a lot: http://drupal.org/node/add/project-issue/documentation We work on issues collaboratively through discussions there, and it allows us to track progress on issues. If you want to keep discussing any of the above, it would be really helpful if you can file an issue for each separate topic (if there are not already existing issues on the topic, you can check by doing a search in the Docs queue).
And we are indeed working on making things easier to understand and find, but there is a LOT of documentation, and very few people working on it, so it isn't perfect, that is for sure. So, we are certainly happy to have your help!
Feel free to also ping Jennifer (jhodgdon) or I (arianek) on IRC http://drupal.org/irc as well if you want to discuss ways you can help out.
Thanks!
ps. Sorry, I missed
ps. Sorry, I missed responding to the question about why the UPDATE.txt file isn't posted online - the txt files that come with core as a rule are not posted into the handbook because currently there is no way to post it automatically and keep it synced with what is actually in core when there are changes.