Updating Watir User Guide (2)

(From wtr-general.)

I have been thinking a lot about updating Watir user guide these days, but I did not have time to start working. I will have some time next week (if not before). I think if user guide is migrated to Watir Wiki it would make contributions much easier, so I plan to do that. If anybody would like to start working on user guide before I migrate it to Wiki, go ahead and grab it from Watir SVN repository, make Wiki page and start working. If you do not know how to get it from SVN repository or how to create Wiki page, please let me know.

I received a lot of good advice about updating user guide. There is a clear need for more documentation on Watir. I do not think that everything should be in user guide. My plan is to make user guide as short as possible and provide links to more advanced topics. Something like:

• Install Ruby.
• Install Watir.
• Open IE.
• Navigate to a page.
• Click a link.
• Click a button.
• Verify some text is there.
• That was easy!
• Want to learn more?
• See how you can work with:
  • Other tags.
  • Various pop-up windows.
  • JavaScript.
  • AJAX.
  • Unit tests (running them, reading them, learning from them).
  • ...
• There is also lots of good documentation on Watir that is at our site. See:
  • FAQ
  • What is Ruby?
  • What is Watir?
  • Is there a difference?
  • Why should I care?
  • ...
• There is also lots of good documentation on Watir that is not at our site. Check it out:
  • Articles.
  • Cheat sheets.
  • Books.
  • ...
• Have question? We have mailing list! When posting a question make sure that you include:
  • Relevant snippet of your Watir code.
  • Relevant snippet your HTML.
  • Error message that Ruby gave you (if any).
  • See example question.

I think this short tips about posting to mailing list are very important. I just hope people will read it.

I think we are ready for several Watir tutorials (at least two).

Take Ruby for example. It has Pickaxe book that you can have on your desk and not be embarrassed when you boss takes a look at it. There is also Why's (Poignant) Guide to Ruby. I remember how my boss was surprised when he saw Why's book. I am sure he thought I was joking when I told him that it is a book about programming. (Hint: cartoon foxes shouting "Chunky bacon!".)

Watir user guide can have "enterprise look", but I would also like to create one version with cartoon characters. I am sure there are lots of creative people here and I hope they will show their creativity. If you would not like to see cartoon characters in Watir user guide, please do let me know, I will not put it at Watir Wiki. (I will put it at my blog and smile to my jokes. Alone.)