How much documentation do you need?

Stacks of documents being measured with a tape measure
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.

Advertisements

Getting to expert: software learning skills

Picture of whole pie
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

Cheeky screenshot of text exchange with a big, uncaring bank
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.

Lessons Learned on Design, Analysis, and Agile

Sticky notes clustered together for an agile planning meeting

When I was at InfoCamp a couple weeks ago, Erin Hawk and Samantha Starmer both spoke about how they’re working to integrate design into the Agile Software Development process.  This got me thinking about some of the successes and failures I’ve seen in Agile projects and how those related back to the integration of the analyst role into those projects.

Since Agile was a methodology created by developers for developers, it tends to be fairly development centric, and a lot of Agile implementations neglect both design and requirements processes.  As someone who has been in the development, analysis, and design roles of systems implementations, I have seen Agile applied with a variety of results.  Overall, the projects that successfully integrated designers and analysts into the Agile process tended to have much better results.

Many projects are unsuitable for developers to be the primary group interacting with stakeholders (that’s another post altogether).  Integrating designers and analysts into an Agile project helps ensure that the end product meets both business and user needs the first time (ie; on time & on spec). Not to mention, it makes the developer’s job easier by cutting through a lot of the ambiguity around a project and reducing the number of times developers will have to change what they’ve made.  Unfortunately, since Agile stresses speed and iteration over carefully planned designs, it’s not necessarily easy to integrate that into the process.

Here are four of the lessons I’ve learned on how to succeed in Agile development from an analyst’s point of view.

1 – Be an agile waterfall

Agile development focuses on rapidly developing, testing, and releasing a product, which has a tendency to squeeze out designers and analysts . However, many projects and products are so complex, and have so many stakeholders, they require specialists (aka designers & analysts) to handle that complexity.

The best Agile projects I’ve worked on keep all of the phases of the Systems Development Life Cycle, but compressed them down into small and fast chunks.   By reducing the project into a cluster of discrete but related deliverables, ie; user stories, you can keep all the phases of the SDLC but still move at a rapid, iterative pace.

2 – Use staggered phases to keep designers & analysts ahead of developers

One of main reasons that Agile has gained so much popularity is that developers and organizations became fed up with lengthy requirements gathering and design processes.  Such processes tend to lead to specs that are out of date by the time the developers get around to them.

By having designers and analysts work one phase (or two phases at most) ahead of the developers, organizations can deliver just-in-time specifications.  Ideally, the development team can put together a rough set of initial stories and prioritize work accordingly at the beginning of the project.  After that, an initial sprint (called sprint zero by some) can give the designers and analysts time to get ahead of the developers while they set up dev environments and take care of any other start up items they have.  Sprint length will vary from organization to organization, but in my experience two weeks is a good length of time for each group to do a thorough job with their current tasks.

3 – Coordination & communication is key

I can’t stress enough that everybody needs to be in constant communication throughout the process.  As analysts are working on requirements, they should be giving developers a heads up on what’s coming down the pipe.  This keeps the developers abreast of changes, and there will always be changes.  While developers are programming a current set of tasks, analysts can provide feedback and integrate any changes the developers want back into the requirements documents.  A good project manager is often key to this process, as project managers are skilled at keeping up communications and preventing the geeks from siloing up.

4 – You’re either all-in or you’re all-out

Either everybody is working on the project, or nobody should be working on the project.  One of the biggest wastes of time  is when development resources get pulled from a project, but the analysts and designers keep going.  In the best of cases it takes 6 months for the developers to come back, and keeping the rest of the team on the project will lead to a waterfall style mountain of  obsolete design documents.  In the worst case, the project gets cancelled, resulting in wasted effort by the design and analysis teams. If one team gets pulled from the project, management should sideline the project until everyone can get back to it.

Those are my 2 cents on the matter, and I’d love to hear about your experiences in integrating design and analysis into Agile projects.

Business vs IT

                After reading the last few posts by nickmalone and Jordan I started to think back about the companies that I have either observed or been employed by and I realized one thing.  There’s a large disconnect between the technical people and the business people.  Now I realize that some of you already know this but hear me out.  I think this causes more problems than many realize.  NickMalone’s post is a great example of what can happen when that gap isn’t addressed, and Jordan’s advice of value added statements is a great way to start fixing the problem.

                As many of you know, I have my Bachelors in Information Systems, which is more of a pure Information Technology degree as it had very few business classes.  I was very happy just learning about how to program and network computers.  The more I learned about networking specifically the more I thought I knew about succeeding in the business environment.  The last quarter of my Bachelor’s degree I took an Advanced Oracle Database class.  That class introduced me to a whole new thought process behind IT, that of IT is there to solve business problems.  Before that I hadn’t really but how IT related to business.  Now some of you may be saying, of course IT is there to solve business problems, what else would it be doing.  But I want you to think about any current or past IT project that you may be on.  What was the purpose?  There are always cut answers of improving user experience or improving the way the business functions but what really was the main goal behind the project.  What was it going to do to help that particular company succeed? 

                That is what I believe is the main point/goal  behind Nick and Jordan’s last posts and what I believe is the fundamental problem in IT departments.  To many IT professionals can make computers do amazing things but they have forgotten that IT is there to help businesses succeed, not the other way around.  I am sure there are cases where it is different but even for companies that specialize in IT consulting or Software design, every IT system should have a purpose and should be directly correlated to a business function.  Once that business goal or function is made aware and focused on I believe that IT projects will be smoother and stop having the Business needs vs. Personal needs issues that NickMalone talked about.

                Now I don’t mean to sound like this is all a problem with bottom-level IT people.  When was the last time you heard about an Executive of a company want to implement some new technology that they read or heard about?  Maybe they heard about want to implement a type of Social Network on their intranet and tell their direct reports to start making a business case for it.  Here again is another face of the same problem.  You shouldn’t make business cases for technology.  You should make “Technology Cases” for business problems.  It might be a slight adjustment but think about how many times technology gets implemented without proper planning so it fails.  If executives, managers and underlings alike were to start the planning and implementation phases of every project linking everything back to specific business problems, businesses would spend less and be more productive overall.

                Now I realize that I don’t have the years of experience of others who are reading this blog so I ask for your thoughts.  When was the last time you started a project that failed?  Did you know the main purpose behind the project?  Was that purpose if you did know it?  Have you seen a difference between projects that directly relate back to business goals and ones that are unclear of business goals?  Now this doesn’t address fully the change management side of things but I but I believe that if employees truly understood how these specific technology implementations helped not only them but the business as a whole you would have less push back, and believe me, being in Security, I know about users pushing back on new technology implementations, but that is a whole different post.

Schooling customers in sustainable consumption

Schooling by Benson Kua

new development in the way Whole Foods displays its seafood has me thinking about how consumers use information in their decisions. The supermarket chain recently started labeling the seafood in its fresh cases with a color-coded system to indicate the sustainability of fishing practices for each type of fish offered. (For example, fish in danger of being over-harvested, or caught using ecologically damaging practices, are labeled Red or “Avoid.”)

Initially, I thought this was an odd move: why carry “Avoid” fish at all? But if I consider the Whole Foods tactic as an information strategy, there seem to be some advantages to giving consumers more data related to their purchases, rather than simply adjusting prices or changing the variety of products offered. I have tried to identify and outline the important components of the Whole Foods information strategy in my analysis below.

Consumers act in a social setting in a supermarket. A consumer may be less likely to order an “Avoid” species in front of other customers, even if she does not personally worry about collapsing fisheries. The social pressure to responsibly consume could impact on the overall demand for certain species.

Perhaps more importantly, consumers gain lasting information from a single transaction. The next time a consumer purchases fish – even if it is not at Whole Foods – he may likely remember certain species labeled “Avoid.” In this way, the labeling tactic could inspire a shift in demand throughout the marketplace, or at the very least cause consumers to ask more questions about the origin of their seafood.

Prices are point-in-time data, and may inaccurately reflect the sustainability of consumption. We suspect many fisheries may be close to collapse, and the negative impact of fishing practices worldwide will affect all points of the food chain. We are not able to price a salmon fillet to capture the opportunity cost of fisheries collapse (the 1992 collapse of the Northern Cod fishery demonstrates some of the complexities of gauging the health of a fishery). Consumers need more information than price alone to make sustainable choices.

Whole Foods sends a powerful message about its perceived role as a corporate citizen. Corporations are supposed to care about the profits in this period or this year. However, sustainable practices require a longer view than quarterly (or even annual) earnings statements can offer. By giving consumers more information, Whole Foods takes the long view on the seafood market, the importance of ocean ecology, and its place as a food retailer, while continuing to give consumers optimum choice.

We are surrounded by information constantly. Curiously, though, the information available to us as consumers in the grocery store is truncated by federal regulations, and in some cases, state laws. The seafood labeling practice at Whole Foods demonstrates the possibilities of giving consumers clear, salient information to encourage sustainable and healthy choices in the supermarket.

(You don’t have to go to Whole Foods Market to refer to the Seafood Watch guidelines. Downloadable guides are available through the Monterey Bay Aquarium.)

Photo by bensonkua. Available under a Creative Commons Attribution-Noncommercial license.

And, why exactly is this a good idea?


illustration borrowed from Flatland.com

We’ve all experienced it before.  Some VP or director has a brilliant idea for a new distribution method, a plan to launch a new product line, or any number of other schemes that have the potential to be a really good idea.  The idea makes its way onto the company’s strategic road map, and resources start getting thrown at it to complete the project in some crazy time frame.

At some point the project will make its way to some smart analyst’s desk.  He starts to do some investigation and quickly finds that either no work has been done to look into the potential costs and benefits of the project, or that the figures being thrown about are little more than someone’s educated guess.  As an analyst, this is when I usually ask, “Why exactly is this a good idea?”  But by then it’s too late.

Businesses often leap before they look into projects, both large and small, without taking the time to delve into the data and use facts to determine if benefits justify the costs. For large decisions, such as new product launches and entering new distribution channels, such an analysis is crucial to the well-being of the company, but is often overlooked or done in a superficial manner. The same is equally if not more important for small projects since such analysis is so often missing.

Taking the time to investigate the value of a project helps reduce the amount of money, effort, and energy we waste on projects that just aren’t worth it.  So, why do businesses so often jump into projects without taking the time to look at the data and make well informed decisions?  I think the answer is twofold.

First, businesses are run by people, and people have more motivating factors than the best interest of the business. The personal (not business) cost of answering these questions can be high.  It takes time and effort to do the research required to make an informed decision.  Not everyone is going to be inclined to put in that kind of effort for an idea they already believe to be a winner.  Furthermore, answering these questions upfront runs the risk of having to kill one’s own project, which can create a conflict of interests between the individual’s ego and the business’s best interest.  The business often loses out.

Second, managers empowered to make decisions do not always have the right skills, tools, or data to identify and access the information needed to make these decisions.  Even if I had the best possible intentions to thoroughly examine my next initiative, if the data didn’t exist or I didn’t know it existed, I would have to rely on my gut or just make up some numbers.  This is often the case in projects with no existing analog.

Alternately, when dealing with projects that extend or modify existing methods, the information to drive such decisions should exist.  However the needed data might be incomplete or non-existent because the designers of the system at the time didn’t bother to store it.  This is problem of design intention and a failure to think adequately for future needs.

In another possibility, the data may exist, but it is buried deep down in the unearthly bowels of several databases and would take an expert to retrieve.  This is a situation where the business decision makers need to have strong relationships with the analytical and technical folks who know how to get this information.

The solution to the problem of making informed decisions is a two-way street: it is equally incumbent upon analytical and technical folks to build relationships with the people running the line of business. Such relationships could save us all from having to ask, “Why, exactly is this a good idea?”