How much documentation do you need?

Used under a Creative Commons License courtesy of gadl @ Flickr

As a business systems analyst, one of things I struggle with is finding the right balance of documentation.  Often times documentation feels like a chore and as Modern Analyst points out, it can seem downright counter-productive in an Agile environment.  Yet, in many situations documentation is necessary for other project stakeholders to do their jobs and to ensure that someone can learn how the system works once you’re gone.  The tricky part is finding out how much and what type of documentation is required.

Probably the most important consideration when determining documentation efforts is to consider your stakeholders.  Who will read this documentation, and how will they use it?  Here are a couple thoughts on how different stakeholders use documentation and descriptions of their unique needs.

Software Developers: If the main users of your documentation are going to be software developers, you might as well not write it.  I kid, but seriously developers do not really need detailed specification documentation, and generally won’t read it anyway.  In my experience the best types of documentation for conveying business requirements and rules to developers are simple artifacts like wireframes and flow charts.  Those, along with a handful of conversations and some white board time, are generally all you need to get developers building to spec.

Testers: The underpaid, understaffed, and underappreciated grunts of the software world ensure that our software works in all those edge cases and  produces predictable results.  It’s been my experience that these guys and gals often need highly detailed documentation to get the job done.  Detailed documentation gives them specific details they need to write test cases with predictable outcomes. Furthermore, testers are often located offshore, complicating direct communication and making detailed documentation all the more necessary.

Business Users: When process owners change, aside from wanting to scrap the entire process, the new owners will generally want some documentation that explains both the purpose of the business processes and how the software work.  Ideally, process owners and business stakeholders can provide much of their own documentation.  To meet these needs, a business case can explain the purpose and goals of the process/system, and some operating procedures or guidelines will provide an overview of the business process.  Finally, the analyst might want to provide a flow chart and some notes explaining how the process and system fit together, along with appropriate references to the more detailed documentation if it exists.

Future Analysts: Often times, I have found myself cursing the people who left behind no documentation on the workings of the system I am expected to modify.  Don’t be that guy.  When reading historical documentation, analysts mostly need to be able to glean business rules, the project justification, and some idea of system processes  from documentation.  These can generally be derived from some combination of the other types of documentation listed above.  As long as the other documents can cover those subjects, there probably is not a need for documentation specifically intended for future analysts.

Unfortunately, each set of stakeholders requires a different type of documentation.  Sometimes this means that we analysts need to write multiple sets of documentation for the same project.  In the end, analysts should aim for just enough documentation get projects accurately built and tested, and enough documentation to ensure future stakeholders can understand what was done.

If you’re interested in more on this subject, Modern Analyst has a great article on requirements specification in an Agile environment that touches on this, as well as recommendations for methods to communicate requirements.

Getting to expert: software learning skills

Getting up to speed on 'Preferred' software experience can be as easy as pie (mmm...pie)

One of my fond memories of working in Finance MIS was a short-lived tradition called “Nerd Lunch.” I and another analyst would log in to a net meeting and work through complicated SQL queries every few weeks. We would brainstorm solutions for ongoing information problems facing our department. I ask you: Has there ever been a more appropriate moniker for an event?

The analyst was my guru. With her help, I went from landing a job where I knew next to nothing about the software I would be using to finding solutions for decision makers in our organization.

I’m writing this blog post because it’s great to get excited about a job posting that sounds perfect in terms of industry, position, and advancement opportunities – but then it’s disappointing to worry about qualifying on ‘Preferred’ software experience. Worrying about software experience may even keep a job seeker from pursuing a position. What follows are tips I’ve found helpful to first get through an interview without perfect software experience, and then to get up to speed quickly in software skills once hired.

For an interview: Likely you will be facing a hiring manager when answering questions about software skills. Before the interview, it is possible you may be able to fully investigate the software – say, with a free trial for more common products. Barring that, prior to sitting down with the hiring manager, I suggest Googling the software listed in the job posting to find its specifications, as well as those of competing software products. This is a particularly helpful step with specialized software, such as enterprise management, accounting or asset management software.

Investigate the capabilities of the software to understand the functionality, and then come up with (intelligent!) questions related to the software’s application to itemized job responsibilities in the position listing. After all, once you get the job, that will be your contribution to the organization. It is most important in an interview with a hiring manager to demonstrate understanding of the role and to express critical thinking skills related to a position’s responsibilities.

Once hired, read a book: Find a beginner’s guidebook to the software if you can. Also, read it. (NOTE: No one really thinks you are a dummy when you read those Dummies books.) Rather than buying it new, I suggest checking out bookins.com, half.com, or posting an ad on Freecycle for a used copy. I’ve always found that starting with these books gives a good comfort level for tinkering in the software, at which point you are ready to sandbox.

Sandboxing: This is when you’ll start breaking existing tools in a calculated way. Set up a dev environment for this step, whatever that may be. For tools that use scripts, like VBA, or query language, like SQL, pretty much everyone learns by stealing snippets from existing tools and modifying for new applications. This is the sort of stuff you can do while waiting on a batch of project work or during down times in cyclical reporting periods. Please do not underestimate the “Help” tool in a software package; these tools tend to get more useful as your grasp on the software jargon strengthens (ironically). There’s no shame in using company resources to iterate and build on your technical skills, particularly if you are the type to check Facebook or text during working hours.

Find a guru: A guru is different than a mentor. This is a person whose geek runs deep, but who has enough patience and time to answer your technical questions. A guru will also have excellent problem-solving skills, in that she (or he) can help you find answers to existing problems by walking you through previously applied solutions in the software tool. Surprisingly, perhaps, a real guru won’t do things like grab your mouse and make a quick fix; that person will have a conversation with you, explore the scope of the issue, and explain in plain language what you need to do. You will learn to deepen the relationship with increasingly thoughtful questions about the work at hand, eventually adding value instinctively. In the long run, a guru’s approach will ideally make you a better thinker.

When this person helps you, be sure to recognize her. Buy her coffee. Send a thank-you email to her boss. Write a blog post about her. Someday, if you care to, you’ll be in the position to act as a guru.

I hope this makes learning new software (or becoming an expert in familiar software) more attractive and less painful. The software is just a tool for the tasks at hand. In the end, you are the element adding value in the position, first by applying software and later by sharing your knowledge.

Photo by Caitlinator. Used in accordance with a Creative Commons 2.0 license.

Putting the Organization in Info Management

You know this is a dramatization of the event because Big Bank doesn't answer texts after 5pm

Information management can be described using a couple of different but fairly similar models. The University of Washington’s iSchool depicts a triangle-shaped model of Information, People, and Technology. However, our readers might notice this blog examines the intersection of People, Information, Technology and Organizations (this model is explained in greater detail by Ping Zhang and Robert I. Benjamin in a paper titled “Understanding information related fields: a conceptual framework”).

We’re square rather than triangular, if you will.

Why do we add organizations? Because gathering and acting on information changes fundamentally in an organizational context. And sometimes, information behavior within an organization can be downright bizarre or frustrating.

Here’s an example: I went out to dinner a few weeks ago with friends, and my debit card was declined (happily, the waiter did his best to not treat me like a deadbeat). Since the card was declined for no obvious reason, I had a mystery on my hands. Unfortunately, customer service representatives (CSRs) at the national bank where I have my checking account were stumped as well.

Eventually, two weeks later – after three calls to the 1-800 customer service line, two trips to the local branch, and a dozen fact-finding missions through the online banking portal – my debit card was still not operational and I had been told it might be because the number had been stolen.

Think about all the failures in my interaction with the bank: I had several types of contact with different outlets of the organization, and none of them were satisfactory.  At least three CSRs were unable to access my account because I had opened my account in a different state (each of the representatives did sheepishly suggest I could open another account at the branch and then they could help me; I declined those offers).

I can do without naming the bank because this isn’t meant to be a Consumerist-type rant. But I think the episode does bring to light the irrational and haphazard information strategies organizations seem to employ. As a person and a consumer, I scratch my head when representatives of the bank cannot answer my questions or help me understand what is happening with my account access. But the madness of the situation also affects the bank employees: imagine the exasperation of working a front-line CSR job and having one’s hands tied routinely in a significant number of common issues.

But for the organization, this information strategy is working on some level. I imagine – the finance industry being particularly yoked by multiple layers of regulation – this national bank has designed its policies and procedures to serve up a savory dish of compliant operational spaghetti. Somewhere, a satisfied auditor completes an X on a checklist when a CSR in Washington cannot access my account, what with its Massachusetts provenance.

This is operational reality in the modern banking industry, and I mostly understand why my encounter with the bank was so dissatisfactory. However, I think such encounters are at the very least opportunities for learning in organizations. Holistic customer experience (a process of design that includes all touch points in dealing with customers, or even vendors, of organizations) should focus on tasks vital to customers at all service delivery points.

Here at infoscussion, we believe information management model has four facets – and that an organization’s needs can be separate from, but equal to, those of the people involved with the organization.