Homework 4: mouseTrap Documentation


Sthayer (Talk | contribs)
(Created page with '<h1>GNOME mouseTrap Documentation Review</h1> The [http://live.gnome.org/MouseTrap mouseTrap Website] immediately opens with a brief description of the tool. It is short and to ...')
Newer edit →

Current revision as of 16:38, 15 October 2009

Contents

GNOME mouseTrap Documentation Review

The mouseTrap Website immediately opens with a brief description of the tool. It is short and to the point, providing information easily accessible to both user and developer by mentioning both what it does and briefly how it works. The only thing that threw me was the term “a11y”, which I then looked up on Wikipedia. It would have been helpful to mention that or link to a page that describes it. Also, throughout the page there are references to both “mouseTrap” and “MouseTrap” - even simple things like keeping the name consistent helps.

Why Python?

The next heading, “Why Python?” was an attempt to describe why the developers chose to use the Python programming language, but fell short in a couple of ways. For one, it assumed an expert knowledge of different programming languages, particularly with the phrase “as we all know” and the first benefits described are applicable to more than just Python. Second, the first person point-of-view distracted from the point of an open source software project, which is community, not a negative dictatorship – implying that it was one developer's decision, not an agreement of a community. The language was a bit difficult to get through and understand, and at this point there does not seem much of a need to explain in detail why the language was picked. Additionally, I don't know what OpenCV is, nor its hardware requirements and why that had anything to do with the project. This section needs clarification, humility, and either explanation of certain terms or links to them.

OpenCV in MouseTrap

Next is “OpenCV in MouseTrap”, and still knowing nothing about OpenCV, I didn't understand the relevance to this tool or to the heading of this section. This would work better as a “Basic Workflow” type of section.

More

The bottom has the other important information. There is a video of someone using mouseTrap, which is helpful to gain a better understanding of the overarching goals of the tool, as well as links to the bug reporter, mailing list, type of license (GPL v. 2), and “Installation” and “Using MouseTrap.”

Installation

The Installation page was useful, providing the dependencies needed and which versions to install, and how to access the code. Documentation is briefly described as being available in the code itself, and there is information on how to access or turn it on. The same pretty much goes for user documentation: “To generate the final users documentation it is necessary to set this flag --enable-docbook in the ./autogen.sh command. After running make there will be some .html files in the docs/docbook/ folder, open the index.html to see the main page.” It would be helpful to have live user documentation on the website instead of having non-contributors have to go through downloading the code using tools they probably don't have and don't know how to use.

Using MouseTrap

“Using MouseTrap” was helpful, though not very clear. The “MouseTrap Arguments List” had keyboard commands for navigating through MouseTrap. I assume this is aimed at developers so that they don't have to hook up a camera or go through the process of MouseTrap as a user, but this is unclear, especially given the link title. The command to run MouseTrap is simply stated, and then the page launches into the “Mouse Movement Methods.” This is very useful in describing the different ways users can navigate their computers using MouseTrap. Each type has a separate page explaining how they work. Oops. These pages do not exist yet. This is a problem that should be taken care of quickly by one of the contributors.

Bug Tracker

The bug tracking tool is Bugzilla, which requires an account even to view bugs. This could be a bit of a turn-off for people who have hung on this far – but can't see recent activity. It also may not be something the developers can control. I made an account and searched for “mousetrap” in the bug tracker. There were only 2 bugs, both unconfirmed from March and June.

Mailing List

This is short and sweet. Subscribing to the mailing list is easy, as is editing mailing list options for current contributors. A glance through the archives shows relatively low activity, and there is a post that appears to be spam or a hacked account, as it's entirely unrelated conspiracy theory on Obama. It does offer a digest option to allow subscribers to receive an email once a day with every message of the day. Without subscribing, I can't tell if there is more than one mailing list for different aspects of the tool, but it seems relatively small enough that this may be unnecessary.

The Code

I looked in the git repository, an HFOSS clone of the code for mouseTrap. The README file is empty – it should at the least have a description of the project and the licensing information; this wouldn't be hard to do. There were some different branches, but their names made their purpose unclear.

ctypes

This is better. The README file, which is displayed below the links to all of the other files, has a clear definition, lists the author, version, and installation notes. Not all files have this information, however, though documents like AUTHORS and COPYING are helpful in this regard. One file has a PGP public key block, another is full of gibberish characters. The subfolder cvtypesopencv is pretty good, including files taken from somewhere else, with their own credits. There could be a little more documentation in these files to explain the methods and how they're working, though this varies greatly – some files are wonderfully documented, and some are less so.

The demo files are a mix of pictures for the demo and files which have no description of their function in the overall tool or why they belong in demo.

mousetrap

This has a lot more information (and files) than ctypes. It even includes some UML diagrams and the documentation is much better. I also found documentation specifically aimed at developers and users nestled in /docs/dock_party.

src

src appeared to have mostly the same files as mousetrap. Documentation is still better here than in ctypes, but lacks consistent opening comments.

The Issues in github seem to be a sort of forum for help fixing bugs, but I wonder if there are more bugs in the bug tracker previously mentioned or if there's a difference between the two. If there is, this should be clarified. If not, then the Issues doesn't seem necessary.

IRC/Chat?

Nope, these didn't seem to exist. The only discussion aspect I saw in the project was in Issues in github, and that was fairly limited. It seems, right now, a lot to take on with all the code I saw, with few developers or activity (recently).

Hacktivation Index

While it's still a bit overwhelming, the (relatively small) community of contributors seems easy-going and welcoming, and I think it would be easy to get started on contributing to the project. That said, it's going to take a bit to dive into the code and figure out where the problems can be fixed; there's still a lot of code, and I've never added to code, I've built from scratch. I learned some Python a few years ago, and would be happy to get back into it, but am still feeling overwhelmed by all of the code and the uncertainty of what it all does.

Clarification, clarification, and minor editing fixes would make this a whole lot stronger.