Add best practices for authoring Project nodes [#997066]

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

Comment #1

mherchel

he/him

English

Gainesville, FL, US

commented 13 December 2010 at 20:28

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.

Comment #2

lisarex commented 13 December 2010 at 23:06

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!

Comment #3

arianek commented 15 December 2010 at 03:36

Status:

Needs review

» Needs work

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!

Comment #4

yoroy commented 28 March 2011 at 23:24

Issue tags:

+prairie

Subscribe & tag

Comment #5

skrossa commented 18 June 2011 at 04:38

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

Comment #6

arianek commented 20 June 2011 at 05:17

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.