Just landed a few changes that had been hanging out in the wings for awhile that I wanted to let folks know about. This has to do with getting flunc into the opencore distribution, a personal itch stemming from having extra steps to set up the ftesting (which I found myself plain forgetting to do).
So here’s where things are::
- opencore’s ftests now ship with opencore (in… opencore/ftests). This should help keep things in sync. For bbb purposes, the ftesting bundle is updated to look at opencore trunk’s ftests.
- flunc now comes with a setuptools extension that allows for the running of flunc tests inside a package from setup.py. This doesn’t provide overwhelming convenience, but does take the guess work out of remember to use -p. Later, this hopefully will grow a bit more sophisticated as a test finder. For now the following command will run flunc (provided your zope is running on localhost:8080). It will also interpret the normal flunc options.
$ cd opencore
$ python setup.py flunc -vw
- flunc is now a dependency for opencore, meaning the flunc test running script is installed everytime you install opencore. And it works the same way as always, so if you choose, you can run the tests like so:
$ flunc -vwp opencore/ftests all
As to which form of invocation works better, it’s apples and oranges (depending on perhaps what you are doing). Framework-wise, there are some interesting things the setuptools command could let us do with organizing, finding and running ftests without changing the simplicity in how flunc works as a standalone script. More importantly, whichever way you run it, you are running the tests in the same way (or explicitly deviating by using the spelling in #3).
Help should be broadly distributed across OpenPlans:
-
General || Specific: We should be conscious to address a range of conditions ranging from the general (How do I use this site?) to the specific (How do I make certain tasks private?). For the beginning phases we’ll need to focus on the general but answer and collect specific questions as they are encountered.
-
Goal-oriented || Implementation-oriented: While we must guide our users through the steps necessary to implement their goals, it is also important that we provide them with examples of what is possible to accomplish. The minutiae of using the site is important, but engaging the user with what is possible is what will get them to use it to begin with and, ultimately, what will keep them with us. Our software is a means to an end: we need to show them what ends are possible before we explain the means.
-
Help-full Marketing
The first place users should receive help is in the text used to describe and market the OpenPlans site and software to (current and) potential users. An example would be phrasing the homepage in terms of the OpenPlans Q&A document. This text is more general and should primarily address potential applications and only secondarily address how to implement them.
This type of documentation includes:
-
Contextual Help
This is the help that deals with specifics as they occur during the flow of a user’s actions. It should be intuitive and anticipate the information the users needs while being unobstrusive.
This type of documentation includes:
-
Documentation
The comprehensive documentation pages are a user’s last resort. It is the place a user goes when all other sources (including the intuitiveness of the design and the contextual help) have failed them. They need to deal with all manner of things from the general to the specific but tend to focus more on implementation than goal-oriented possibilities
This type of documentation includes:
