Usability, Consistency - RULES!

I just read an interesting list of "new laws" at http://pfeifferreport.com/trends/trend_userexperience.html (found from http://pyre.third-bit.com/blog/archives/000414.html (found from http://planet.python.org/index.html) .

I find that a number of these resonate strongly with me, and put in words some of what I am trying to achieve with pywinauto.

I should print the list and post it above my desk - then when I go to refactor or add new code I can ask myself if the changes obey the rules :-) (I think 6, 8 and 9 are the ones that will be most useful day to day).

Getting the text of a container control is maybe not that critical for the everyday user of pywinauto - but it should be easy to find if they do need it. Here are some examples of how inconsistent this is at the moment...

  listbox.ItemTexts()[item_index]
  ListView.GetItem(item_index, subitem_index)['text']  # returned item is just a dict
  TreeView.GetItem(0,2,4).Text()
  Header.GetColumnText(col_index)
  Statusbar.GetPartText(part_index) # at least these last two are similar
  Rebar.GetBand(band_index).text # attribute set in returned ctypes structure!

These kinds of inconsistencies do not help anyone learn pywinauto (I hadn't realized it was so bad :-) )

Just as a counter point to above - it's not all so bad.
control.Select() is defined for most classes and behaves (hopefully) more or less as expected.

So - going forward I am going to try and ensure usability and consistency of pywinauto.

The other point is documentation - there IS documentation for pywinauto - but I definitely do not consider myself a tech writer. From reading the rules - it also occurred to me that my documentation is lacking in a major way - it is not easy to find what you are looking for.
I think a new set of pages which describe in a succinct way how to work with controls will help.

E.g.
Operations on controls:

ListBox
     Select
     SetFocus
     GetFocus
ListView
     Select
     IsSelected
     IsChecked
     Check
     UnCheck
     IsFocused
TreeView
     Select
     ...

Even the list by itself helps - in that it would allow you to see what is available more easily then browsing the current documentation.