You’re joining a new project. Maybe it’s at the very beginning, or maybe you’re joining a project that’s already in progress. I always suggest that analysts start by finding all the documentation they can and reading through it. But what if there isn’t any?
One of the biggest challenges we faced with our CRM conversion project was a lack of documentation. There was very little information on how the data was structured and absolutely no documentation on the custom code that managed our certification program. And I’m sure some of you have faced this one too – the people who developed the data structures and wrote the custom code were long gone.
Let’s be honest. Very few people like writing documentation, but it’s really important. In an earlier blog, my colleague Ali pointed out that Just Enough Doesn’t Mean None!. Ali explored the role of a BA throughout the life of an agile project. I’d like to narrow that focus down and talk specifically about documentation. How do we do “just enough”? Here are some key thoughts and a few hints to help.
Determine a Level of Formality and Detail That Works
I recently had a student in class who, like me, remembers the very early waterfall methodologies (SDM-70, anybody?). We reminisced about bookcase shelves full of three-ring binders containing all the requirements documentation for our projects. A project would literally have hundreds and hundreds of pages, and there were prescribed templates that had to be filled out. Even if a particular section wasn’t useful for your project, you still had to complete it.
Hint #1
“Documentation” Can Be Any Usable Representation
We’ve come a long way from those days. When I say “documentation”, I now envision it as something very different than those text-based templates. I rely very heavily on visual techniques and collaboration tools to develop my requirements information. As an example, this is a draft of our decomposition diagram for the CRM functionality. Having it online made it easy to share and mark up, and the visual nature made it easy for the team to review:
Hint #2
Only Provide Detail When It’s Needed
We did more detailed documentation on certain functions where there was complexity or a lot of unknowns. As an example, we didn’t do more detail on adding a new student to the CRM because we all understood that well. We did do more documentation on more complex features like the certification program:
Hint #3
Only Formalize If Necessary
I could certainly have taken the time to polish this information and put it into more formal documentation. I didn’t, because in my opinion, there was no value in spending time to do that work. It was “good enough” in this informal representation.
Understand the Purpose
Our Miro workspace was great for development and testing but it wasn’t what we were going to need in the future. It’s important to think about *all* the purposes that your documentation will serve.
Hint #4
Set Yourself Up for Requirements Reuse
I would have paid big money to have copies of the requirements documentation from the original CRM customization. It would have saved countless hours of work and given me a lot more comfort that I wasn’t missing anything.
Many items you develop to support development and testing can be useful after the solution is deployed. Process maps, data models, business rule models…all of these can be really helpful for future development efforts. On the other hand, some items – like a current-state process flow – are not especially useful in the future. Don’t take time to formalize those types of artifacts.
Hint #5
Think Beyond Software Development
In addition to future development efforts, I needed to develop documentation to support operational use. I realize this may or may not be part of your typical job as an analyst, but here’s my point – think about needs beyond building and maintaining software. Your requirements documentation may contain information that’s useful in other ways.
And again – only develop as much as you need to. Our operational documentation doesn’t cover every feature or function in the CRM. It only covers things we’ve customized or that are not intuitive.
Make It Accessible
Documentation is only useful if people can get to it. My advice in this area is pretty simple..
Hint #6
Make It Accessible
Everyone who needs to use the documentation should know where it is. And make sure they actually have access rights for where it’s stored.
Hint #7
Control Document Versions
Have you ever discovered that you have team members looking at different versions of a document? There needs to be a single source of truth for documentation, and yet many of us still attach documents to emails and send them out. That’s almost guaranteed to result in somebody missing the most recent update. Instead, I recommend that you:
- Create an agreed-upon place to store the most current version of any document
- Encourage online viewing and commenting using a shared document. Try to avoid having lots of emails and document versions floating around
- Move outdated documents out of the working folder – our not-so-creative solution was to simply create a folder for “Old Versions”:
Wrapping It Up
Documentation certainly isn’t the most glamorous part of an analyst’s job, but it is one of the most important ones. You can be true to the agile mindset by really thinking through how your documentation will be used. Once you know that, you can make it just formal enough and just detailed enough to serve its purpose.
Best,
K.
Get the rest of the story!
This article is part of a series that we wrote based on challenges we faced during our own CRM conversion project in 2024. Each month we highlight a particular challenge and share tips, techniques, and tools you can use if you find yourself in a similar situation.
Kathy Claycomb
Managing Partner, Lead Expert
Kathy Claycomb brings over 35 years of experience to the classroom. She has participated in all phases of solution development using everything from agile to waterfall methodologies (and quite a few in between). Before joining B2T, her career spanned roles from application developer to Senior Director of Services at various organizations. Kathy has broad industry background including transportation, manufacturing, insurance, energy, healthcare, and banking.
Kathy’s first love is teaching, and throughout her career she has always managed to spend a portion of her time instructing. She has an engaging, highly interactive teaching style that ensures students leave the course with a thorough grasp of the material. Her students consistently praise her teaching abilities and her talent for drawing on her personal experience to enhance their learning.
Kathy served as the Technical Editor for Business Analysis for Dummies, 2nd Edition.