[Lessons Learned] Business Analysis Documentation

Random Observation/Comment #512: You never start working thinking “Man, I’m going to become a PowerPoint guru”, but it happens quickly.

After working for over 5 years on at least a dozen successful projects as a business analyst for an investment bank, I’ve seen all flavors of documenting business and functional requirements. It’s not that one is better than the other (since they all show similar information), but certainly some are more effective for communicating the purpose of the document to a specific audience.

The key to being a good BA is also knowing the right tools for the job, so here’s what I’ve seen as a general banking trend for documentation:

Docs

• Summary: This is the most standard and fundamental way of producing a document. It focuses on business text and for me is usually a consolidated set of requirements scribbled from notes, random conversations, and emails. For the most part, this is just a formality, but it does require sign-off from the business. In reality, I don’t think this document ever gets fully reviewed or read. For functional requirements, you’ll see many more diagrams, summaries, and use cases.
• Intended Audience: all, but mainly business, management, lead dev, and project managers
• Actual audience: other BAs or PMs looking for information to put together a deck.
• Content: Text describing clearly the objective and outlining the business context and requirements for delivery.

Slides

• Summary: In business jargon, we call this a “deck”. This basically means a condensed summary in slide-content form to let senior management quickly review and take lists of broad strokes to escalate. If your project has high visibility, there will probably be a lot of decks out there giving this information. In very rare occasions for the banking industry, you’ll find elegant Presentation Zen decks for actual presenting through the material without reading from the slides.
• Intended Audience: senior management and PMs
• Actual Audience: other BAs and PMs who are learning the business context and technology from the slides (instead of reading through a document)
• Content: Diagrams galore with bullet point ideas that summarize something that probably requires a lot more examples to teach. Pretty pictures and graphs.
• Beware: Death by PowerPoint. It’s been a more prominent trend of abusing PowerPoint for everything – screenshots, documentation, design mock-ups, etc. People like to be able to independently read the PowerPoint and not necessarily need to even have a person present to give the presentation. This drives me crazy, but I’m just as guilty to provide “slide versions” of full docs.

Spreadsheets

• Summary: Every business user I know is a spreadsheet power user. They use it for collecting all data and running personalized reports. It’s become the core method for keeping track of any calculations and verifying information on formulas and templates. In some cases, I’ve seen spreadsheets used to list requirements and project plans. There’s a separate project plan application for this, but I’ve actually seen quite a few amazing data dictionaries and really comprehensive documentation written within spreadsheet pages. The table of contents or “readme” type of main sheet maps to each individual sheets for context.
• Intended/Actual Audience: BAs, PMs, Devs – book of work view
• Content: Reports, tables of data, data dictionaries, lists of book of work items, pivot tables

Wikis: Confluence/SharePoint.

• Summary: Wikis are online shared pages/documents that can be edited by your set permissioned users (anyone in the case of wikipedia). For me, it’s a powerful way of representing a larger summary of information to other groups who may be interested in our projects/groups. You can embed photos/diagrams and share a lot of updates from Project Managers. Confluence also communicates with the Atlassian JIRA product which is used for keeping track of tickets and BOW items.
• Intended/Actual Audience: Everyone, especially other teams
• Content: Pretty much everything public. I love wikis for the ease of use and sharing of the full story around the higher level projects covered by a team. I highly recommend organizing this as a story and encouraging separate groups to contribute within the same space in an organized manner. Crowd source and share that Subject Matter Expertise.

What do I use? It depends, but in my system of learning and showing what I’ve learned, I like to begin with creating PowerPoint slides for everything I’m learning. It’s an easy way to draw diagrams and visually describe important pieces of information I’ll eventually need to dumb down anyway. It’s very clear to me that people hate reading documentation as much as people hate writing it, but it’s one of those necessary evils.

As a final thought, I’d personally recommend trying to explain things visually with process flows and architecture input/output landscape diagrams for the broader context of what you’re trying to build.  I usually copy the PowerPoint slides and share them within the wiki so there’s just one place to keep everything instead of uploading/check-outs within SharePoint. It’s also a given that you should always comment your code. It’s a great best practice and I often comment my SharePoint slides in the ‘Notes’ section for the same reason of refreshing slides with content I intended to describe.

~See Lemons Document