After reading the email announcement and project description for this project, I feel very excited and happy since I believe this will be a great resource for the community that could save myself and many others a lot of time. I checked out a fresh copy from CVS and started at the README.txt, which is mostly very complete and well-written -- nicely done!
Here are a few minor suggestions for improvement on the README:
A) Wrap the text to 80 columns wide.
B) The change history is usually put in a CHANGELOG.txt file separate from the README.
C) The formatting of the changelog contains a fair bit of duplicate information. For example, instead of this:
4. FIXED: Issue 170222 http://drupal.org/node/170222. SOLUTION: file method fixed.
You could say even more information with less text:
4. http://drupal.org/node/170222 : Fixed the 'file' method for fetching patches.
Or, you could at convey the idential information with even less:
4. http://drupal.org/node/170222 : 'file' method fixed.
D) The formatting of the "Dependencies" section makes it hard to read, especially without the 80 char line wrap.
E) The "Directory Layout" isn't exactly right (e.g. the dir is really 'log' but it's mentioned as 'logs'), and should mention this is what the directories should look like *after* you install all the dependencies. ;)
F) The "Installing" section should just point to the INSTALL.txt file, instead of duplicating a subset of the info.
G) I've found that to-do lists don't work well in README.txt or even TODO.txt files directly checked in to your project's CVS. As soon as you start adding branches, the lists become a serious pain to maintain. I've moved all my project's TODO lists to wiki nodes on g.d.o and just include a pointer to each one inside the README.txt for the projects.
Thanks for producing such a wonderful tool and doing a great job on the release and documentation (INSTALL.txt looks great, with the possible exception of the 80 char line wrapping).
Comments
Comment #1
allisterbeharry commentedThanks for the review Derek, I was looking for feedback and boy I am getting it - keep the issues coming :).
I'll try to wrap at 80 cols all text files in future and make sure they are readable at all resolutions. I'll make the changes you suggested and review the entire file to make sure the content is in sync with the code (This is the start of the dreaded Winter of Documentation...)
Comment #2
figaro commented