Night of the Living Manual

As I mentioned in my previous post, I have had some issues recently with SourceForge, so I shall be using that as my springboard into living documentation.

While attempting to discover how to add a member to my project, I tried exploring the site somewhat, and then finally gave up and looked at the help documentation.

Here is the link I found: http://sourceforge.net/apps/trac/sourceforge/wiki/Add%20a%20project%20developer

Needless to say, that did not work. If you check the history link for that page, it was last updated two years ago.

This goes into 'what is living documentation?'

Living documentation is documentation which is updated continually throughout the life of a software project. This includes things that the end user will see (user manuals, help files, support pages), and things that are internal to development (requirements documents, scope documents, defect tracking, test plans and test cases).

I feel like making a seasonal pun, feel free to skim past the next line.

You don't want to allow your documents to rest in peace, because more than likely, they'll rise back from their graves to bite you later (and I'm sure that becoming an undead document yourself would be a trifle inconvenient, not to mention painful).

Living documents help bring new team members up to speed quicker, and allow users to find out about new features or newly found bugs (and temporary work arounds) that might otherwise remain mysteries. They also keep you in compliance if you are working in a regulated industry. They also prevent inconsistent knowledge within a project. If Peter the Project Leader reads an old document, and assumes that feature x is still in, when Terry Team Lead had it removed two months ago, Peter will not be pleased when he finds out that he sold a non-existent feature to a client.

So, why is it that living documentation dies?

• People get busy. Software teams aren't always staffed quite as well as they would like, and documentation sometimes falls by the wayside, especially if a lot of changes happen rapidly.
• Documents get lost. This happens especially when teams are distributed, documents are passed around outside of any version control, or document control systems are changed (switching from word to a wiki, for instance)

To prevent these issues, you can designate someone on the team to have a recurring task to make sure that all of the documents are updated. You can also push people to get into the habit of updating documentation as soon as requirements change, bugs are found, or scope increases/decreases. And of course, nothing helps more than practice.

So, in a reverse of my last post, does anyone have examples of great documentation they have had the pleasure of using?

Bad UI Design, or "Wait, I can do that? Why didn't you say so before?"

So this is a topic near and dear to my heart for several reasons, and I'm talking (well, typing) about it now for a few reasons:

1. I've had issues with projects with terrible, bad, or just incredibly unintuitive UI design
2. I've recently tried to start a project on SourceForge, and found that I cannot seem to add another user to my project.

Why are these things frustrating for me?

• Well, I use software, and when I can't find something I need on a website, in a program, or on my OS, I lose productivity and/or sanity (depending on the problem).
• I also test software, as some of you may have figured out from the title (I pride myself on my subtlety), and a bad UI design not only sometimes makes it difficult to test (some non-standard GUIs are more difficult to automate than others), but I also consider these to be Usability bugs.

(As an aside here for those of you unfamiliar with the term, here is the wikipedia article on usability)

I consider usability to be one of the most important aspects of a program, right after and sometimes neck and neck with functionality, and attempt to push for these bugs to be fixed quickly.

The reason for this is fairly simple to demonstrate.

Think about the last time you went to a new website, or tried out a new program (alternatively, go to a new site right now, I'm sure you can find one soon. I'll wait. Back? Good.)

Was there one thing you wanted to do in your program, or one piece of information you wanted to learn from the site, that you just could not figure out? How long did you keep trying with that site or program? 2 seconds? 10 minutes? After a while, you give up.

And that means that the software failed. Whether it has the most miraculous features, the fastest, most efficient algorithms, it means nothing if your users can't find them, or can't figure out how to use them.

So, what was the last feature you tried to use that you just couldn't find/use?

Burning some XP or I don't like wearing shoes, but I do use them

So my blog post this time is a bit different. I figured I would just put what I've been doing recently, as well as what I plan on doing:

1. Japanese: I've been working with a group of friends online and in person for learning hiragana (so far). Mostly I can recognize 1/3 or so of the characters. My plan is to be able to write and recognize all of them by the end of October, as well as be able to pronounce/recognize some basic words and phrases. Our group is using this book: http://www.cheng-tsui.com/store/products/adventures_japanese
2. Braille: oddly enough, SEP (Software Engineering Professionals) has an interactive art project with a braille board. I've found that I've started to recognize a few of the letters when I go by it, so I've been trying to actively learn the patterns.
3. Reading The Passionate Programmer: It's a book about being enthusiastic and successful with your work. I'm finding it actually really interesting so far, and I've been trying to apply some of those lessons to my career, which brings me to...
4. Shoes: This is a GUI package for Ruby. I'm enjoying it so far, and I plan on dipping into it further. Should be nice and simple to learn (since I've never written any real UI before, all of my programs have been command line). More information at: http://shoesrb.com/
5. Exercise: I've been going to the YMCA recently, it's been one of my favorite decisions so far. I've been going at least once a week, and usually twice a week, as well as walking more often (I sometimes now walk home from work, it's about 2 miles). 

Implicit vs. Explicit communication

This blog post was sparked by something that happened a few weeks ago, something completely unrelated to testing, but which, I think, has a lot of lessons for testing (as well as general office communication).

I had offered to emergency-GM for an L5R group (Heroes of Rokugan, if you feel so inclined to check it out). Long story short, the game ended up not happening due to the bad timing of trying to find a GM at the last moment, and having two players in South Korea.

What happened next, however, was a fun comedy of errors.

I had started off an email thread to get things rolling, including all of the players, as well as the three GMs who were generally free, including myself as (what I thought) was an alternate in case they needed me.

One of the organizers trimmed the list back to just myself and the players, without explicitly telling me she was doing so (I found out later that the other GMs had contacted her, with no one passing along the information to me).

This went to the day before the game with me innocently asking who the GM was, and finding out it was me. Unfortunately, I had already made plans (seeing as no one had actually asked me to GM, and I wasn't their regular one).

Had either I said that I needed to be asked to GM, or someone had explicitly asked me to GM, things would have worked out okay.

So, how does this apply to testing? In a few ways:

• I am sometimes bad about being explicit in my speech and writing. I tend to assume people already know what I'm talking about. It's one of the habits I am trying to work myself out of.
• Tests should make clear what they are testing. Tests shouldn't be left floating with no clear connection to their requirements. Without some good connection to the requirements, it is hard to keep the test maintainable...as new testers have to work harder to find out what a test does, what requirement it covers, and how thorough it is. Good, descriptive comments and logs go a long way.

So, how about you, any bad experiences due to poor or implicit communication?

Productive Antagonism: Or how to complain and get paid for it

So I was at this month's IWST meeting (for those of you who don't know what IWST is, go to these links http://indianapolisworkshops.com/ and http://www.meetup.com/indy-testers), and my primary lightning talk was about Antagonism.

Specifically, I was talking about Constructive Antagonism and how it can assist in the design of software systems (note that these are not actual terms used by anyone but me, I just enjoy capitalizing words to give them emphasis).

I define Constructive Antagonism as the process of challenging ideas for a software project in order to suss out potential problems with the design. Preferably, you would want to start this process as early as possible, in order to prevent wasted effort on bad ideas, ideas that are too tangential to the main product, or that just aren't feasible for the project (at least in the current iteration).

It turns out that my idea was hardly unique, as a few people at the meeting had mentioned similar ideas:

Mike Kelly shared The Six Thinking Hats group discussion tool. (Wikipedia link) and pointed out that it has a hat similar to my idea, and the whole system seems to be similar to what I was thinking of (people play roles in order to get new perspectives on a problem or idea).

Rick Grey shared some of his own experiences, and advised that attempting to have the antagonist role should be temporary (no one wants to get the label of 'the bad guy' on all of his or her projects), and that the role requires a bit of credibility within the group that you practice it (otherwise, there are problems of respecting that role).

We also ended up talking about potentially taking the 6 Hats idea and applying it to an actual company's project in town at one of our next meetings. I'm hoping we get to, as I'm excited to see if my idea works out.

As for my personal work with this...I try to be the antagonist during testing efforts, or discussing bugs. I try to find the worst-case that could result from us not fixing a bug, or not paying attention to a feature or feature-set. I've noticed that it feels like it has about the right mix of results:

1. There are a number of times when the idea I challenged was at the appropriate level (the bug didn't need to move up in priority, the feature didn't need more testing), but after the discussion, I think we all felt that the issue was fairly thoroughly discussed, and we were comfortable with it, which was part of the goal. I don't ever want to feel like I accepted an answer just because it was quick.

2. There are sometimes when the discussion resulted in a bug getting pushed up, or new testing being done (which resulted in finding some good bugs).

3. Sometimes, I just enjoy being pedantic and argumentative. I'd like to think these are rare, but my coworkers would be the best people to ask. ;)

So, my question for the readers:

Have you ever found yourself in the situation of The Antagonist, and did it help, or hurt, what you were doing at the time? (Note that this does not need to be software-related).

Baby Bug Report

So this blog post comes from a conversation I had at SEP's game night a few weeks ago...this is what happens when you let a software tester into a conversation about babies.

Enjoy!

List of defects for Human 0.0.1 (Iteration BABY):

Note: Guys, I know it's an early build, but still, maybe we should have held off until the next iteration or two...maybe we should shelve this until iteration TEENAGER...

1. Incorrect size.

    The baby does not meet minimum sizing standards, as stated in the requirements doc. Reference HMO_SPN_SZE

2. Facial I/O port does not follow communication standards

    Even checking for localization, none of the commands given to the test unit resulted in the expected behavior (though some giggling and drooling was observed), likewise, the unit could not communicate functionally. Reference HMO_SPN_TLK
   
3. Unit fails to correctly store inputs

    Sometimes, after feeding inputs into the unit, the inputs are rejected, usually expelled somewhat violently (and messily, my work station has needed cleaning frequently this week). Used inputs BRST_MLK and STRND_PEAS, as recommended in the documentation. References HMO_SPN_VMT
   
4. Unexpected Outputs requires DIAPER workaround

    My test unit exhibited frequent (and odiferous) unexpected outputs, despite several attempts to debug, I have not found the source of the issue, but at least with the DIAPER workaround, I can continue my testing with a minimum of mess. Reference HMO_SPN_POO
   
5. Volume control is broken

    At various points, the Unit seemed to encounter an error, and emited an audible message (see next defect for more details) and I was unable to find the configuration for turning down the volume of this warning. While I cannot find a specific requirement on this, I've made a change request...as I doubt our users wish to be deafened. See Change Request CR_CRYBBY
   
6. Audible warning message too generic

    At various points, the unit requires inputs, changing of the DIAPER workaround, etc. It emits a piercing noise for each of these. The error message, however, is generic, and should be tailored to each fault. Reference HMO_SPN_WAIL
   
7. Unit has virtually no security

    During testing, I noticed that the test unit frequently caught viruses, specifically DIAPER RASH, SNIFFLES, COLIC. While the unit recovers, the process is pricy, requiring specialists. Reference HMO_SPN_SCK

8. Locomotion is impaired

    While trying to execute the command WALK, the unit was unresponsive (save for some drool and gurgling). I then attempted the simpler command CRAWL, still no response. I believe this to be a separate bug than #2, though I could be wrong, as I have no way to verify it is receiving my commands. Reference HMO_SPN_TDDL

9. Installation time is far too long
   Installation of the Test Unit took 9 months. Even after attempting to allocate more resources, this was still the case. During this time, the installation hardware also seemed far more sluggish and unresponsive to certain request. The last part of the installation was the worst, with much hard drive thrashing and almost violent reactions from the hardware. Please investigate. Reference HMO_SPN_LBR

10. General lack of functionality

    After extensive testing, the test unit seems to have little to no redeeming qualities, simply sucking up resources. While I normally don't like to give suggestions, this time I do have a Modest Proposal for its usefulness in the current state...

New Workplace, Old Faults

Hello all,

So it's been about a month since I started my new job, and I've learned/reaffirmed a few things:

1. No matter what your job is, bring a pocket knife, it's useful. 
2. Something will always go wrong with a project, always.
3. I am absolutely terrible at taking criticism sometimes.

It's the last one I wanted to address in the post.

So I have known this for a while, but I've always been somewhat shielded from it at work, as I've always worked as the sole software tester, or the most senior one, so it was easy enough for me to assume I was always right (or at least, right on the things I felt sure of).

So why did I go to a larger company where I knew this would happen? A few reasons:

• I wanted to learn how to work with a team of actual software testers, where I wasn't the only one with experience.
• More specifically, I wanted to learn how to deal with criticism, whether it was correct or incorrect, polite or impolite.
• I wanted to learn how to give criticism in such a way that it helped someone, not just frustrated them, and the best way to learn that (I think), is to get some criticism yourself.

So after a month...well, I'm still frustrated most of the time when my work is criticized, and I still mentally make excuses for why someone else picks apart my work.

On the plus side, I've actually listened to the critiques I've gotten. I've incorporated them into my work, and, I've asked questions as to why certain things were brought up.

So while I might not ever enjoy being critiqued, I at least feel like I can get something useful out of them, something I hope to not lose sight of the next time a code review or similar comes back.

So, I suppose as a challenge for anyone posting...how do you deal with or give out critiques?

Take care all