This module needs better documentation

This would be a good place to add your suggested documentation (or just tid-bits for other users) as a way to assist with the module's development.

The README can be patched like any other file, I'm happy to commit updates you supply for it.

As for your example above, I'm not sure if things like this belong into any of the docs supplied with the module. The suggestion from above is very specific to the question raised within the issue and therefore should be kept within the issue queue as others may want to comment as well.

It would be great for quite a few modules I came across to have more up to date, more comprehensive information available "out of the box" but my experience is that the supplied docs may get you started (sometimes not even that) and it's the issue queue you need to look at for more specific questions.

I'm a neophyte to patching, Drupal or otherwise. Would the attached patch file with a couple typo corrections be usable in updating README.txt ? (back in the day, we did patches with ox-drawn carts).

If I can get the process figured out a little better, it would allow me to submit other patches to code/documentation and, if useful by the maintainers, put in place in the module.

@gcbound, I would agree with @larskleiner that the issue queue is probably a better place to ask questions. Out-of-the box documentation sometimes suffers in the grand scheme of things. If you wanted to work on fleshing out the documentation, i would also happily commit as patches come in.

In any case, your patch appears to apply cleanly to 7.x-1.x, albeit with whitespace errors. As a matter of best practice, I like to commit squeaky clean patches. This page ...
http://drupal.org/node/707484
... is the quick and dirty guide to generating patches. One particular point of interest is step 11 under Quick and Simple Patch indicates a naming convention that is handy for maintainers:

git diff [branch] > [project_name]-[short_description]-[issue-number]-[comment-number].patch

Makes it easier for us to associate a patch with an issue.

Would you be interested in re-rolling an error free patch? Keeping the documentation clean is just as important as any other file in the project.

Here's a list of steps and notes I made to myself during the process and an attached patch file that I hope is squeakier clean :)

Steps for Creation of Patch

1. git clone --recursive --branch 7.x-1.x http://git.drupal.org/project/google_appliance.git
this clones that branch into a local directory named "google_appliance"

2. cd google_appliance

3. git status (or git branch)
shows me that I'm using the 7.x-1.x branch

4. determine the issue number that I'm working with, for future use. According to http://drupal.org/node/707484 ("More git commands") the issue number can be determined from the URL of the issue page itself. In my case, the issue pages is http://drupal.org/node/684814, so my issue number is 684814.

5. git branch 684814-fix_documentation_typos
Step 7 of: http://drupal.org/node/707484: the command above creates a new separate local branch to which I'll commit my changes to README.txt. In the local branch, I've used "fix_documentation_typos" as the "IssueDescription" described in step 7. (It's not clear from documentation whether the convention is to use some variation of the issue description at: http://drupal.org/node/684814 ("This module needs better documentation") or one of your own choice, so instead I've chosen my own.)

6. git branch
see if my new branch was created

7. git checkout 684814-fix_documentation_typos
switch to the branch '684814-fix_documentation_typos'

8. git branch
verifies I'm using my new branch

9. git config --list
check that your username and email address are as desired

10. Make changes to the README.txt file to correct typos

11.
git status
git diff
git commit -a

This is step 10 of: http://drupal.org/node/707484.

12. git diff 7.x-1.x
Review the changes that will go into the patch

13. git diff 7.x-1.x > google_appliance-fix_documentation_typos-684814-4.patch
creates the patch file (hopefully) using the correct naming convention. In my case:
"google_appliance-fix_documentation_typos-684814-4.patch"

14. Double-check line endings and directory separators
Under "General patch guidelines" at: http://drupal.org/node/707484 Windows users are directed to use Unix line endings. One method suggested is to pipe diff output through dos2unix. If you're not using Cygwin on Windows, there are other dos2unix Windows binaries available (http://stackoverflow.com/questions/313178/whats-the-best-way-of-doing-dos2unix-on-a-500k-line-file-in-windows). For example: http://www.bastet.com/

As the README.txt file looks to have been created on Windows initially (0x0D0A newlines), I think it makes sense to keep the newlines as they are. In most coding I'm assuming I'll want to convert any Windows newlines to the Unix counterpart.

I appreciate the help. It'll make it easier for me next time. If you have suggestions about the revision, I'd appreciate your help.

Hans

I've been looking through the code trying to figure out how it works. In the process I made some fixes to minor documentation typos as I went along. This patch includes the changes I'd had in the previous one.

This issue is a bit vague, so I'm not going to change the status, but a definite '+1' vote for committing the spelling corrections in #6.

@gcbound, the in-depth steps at #5 would probably be highly useful to those unfamiliar with working with patches. You might consider adding them to the comments on the patch page (707484), or even adding another page within that section. Thanks for helping out with documentation; this has been committed to dev: 16deb05.

See stable release 7.x-1.11.