Posted by janusman on December 13, 2010 at 6:36pm
6 followers
Jump to:
| Project: | Documentation |
| Component: | Other documentation issues |
| Category: | feature request |
| Priority: | normal |
| Assigned: | Unassigned |
| Status: | needs work |
| Issue tags: | prairie |
Issue Summary
I am writing this inspired by this post from @lisarex : http://growingventuresolutions.com/blog/module-owners-how-make-your-modu...
Project nodes are the main way to learn about what a project is/does, and there is very little on D.O about guiding project mantainers create *good* project pages. The most I could find was the "Project page" bullet point #3 on http://drupal.org/node/188986, and while I think it's a good start I really feel this deserves more than just a paragraph =)
So... I went ahead and created the handbook page Tips for a great project page, and linked to it from the above bullet.
I'd love some feedback.
PS: I have not done documentation in quite a while and I apologize if I overstepped some rules by doing the above.
Comments
#1
Good idea on this. I just posted over on Lisa's blog, screenshots are key...
Screenshots of both the admin and user-facing interfaces helps out very much. If you can't do multiple screenshots, just combine two into one.
#2
Thanks Alejandro! Thanks for creating the issue :) We can refine the docs page to meet style guidelines as well.
I think I'd prefer the docs page to be more detailed, like my post is. Looking forward to hearing more comments first!
#3
agreed - this page could be really useful, but needs a lot more detail. i think it should probably be a child page of http://drupal.org/node/314494 as well.
the style guide is here http://drupal.org/node/338208 for reference, though will review it for this once it's more complete.
i think this could stand to become a section on project documentation best practices (something that's been on my mind for a while...) i think jhodgdon said there might be a section like this somewhere, but i'm not sure where it is!
#4
Subscribe & tag
#5
A guide for a good project page is a great idea, as is project documentation best practices!
But arianek, when I try to go to the URL mentioned in your comment (http://drupal.org/node/314494) I get "Access denied"…
Things I would like to see specifically mentioned are not just Tutorials, but links to the current README.txt and (if any) INSTALL.txt as well as the Drupal.org Documentation page (which every module really ought to have).
It seems to me that a link to the the README.txt and INSTALL.txt for each module version ought to be something that the project page could be made to link to automatically, but until such a thing is automated an explicit encouragement to project page maintainers to add links manually would be a good idea.
I've gone ahead and added these points to the bullet list at http://drupal.org/node/997024
#6
Hi - the node 314494 was a page with very little content called "How to be a good maintainer" - not sure if it's worth writing up a proper version of it... ;)
Looks like good additions.
#7
also (couldn't find this last night) #1142004: Create Module Docs landing page standard