Documenting Your Agile Applications

Neil Benson: [00:00:00] Remember the saying, "Always code as if the guy that ends up maintaining your code is a violent psychopath who knows exactly where you live." Trust me, I've been part of some of the managed service provider transitions, and those companies seem to have a hiring preference for psychopaths. Some even have a policy, I'm sure. 

Hi, this is Neil Benson. Welcome to Amazing Applications, episode 124. You'll find show notes and a transcript at https://AmazingApps.Show/124. 

Just before we get started, I've got a bit of a roll call of recent Customery Academy students to celebrate. Olha Kucheriava from Kiev, Ukraine at 3Shape, Adeel Arshad and Gary Bannerman from the Incremental Group in the UK for completing my Scrum for Microsoft Business Apps course. Simon Williams, he's an independent consultant in the UK for achieving his Professional Scrum Master certification. And the cohort for my first Winning Agile Projects masterclass. From ITK Consulting, Canada, there was: Conal, Doug, Deeana, Steve, and Stephen. From SyncSci in the US, there was Doug and Debra, and Hamish from AppRising in New Zealand. Thanks everyone. 

You can visit https://Customery.Academy to find out more about the programs I offer to help Microsoft customers and partners build amazing, agile Dynamics 365 and Power Platform apps. 

I had a coaching call recently with a Customery Academy student from my Scrum for Microsoft Business Apps course. He's a 15 year veteran of Microsoft business applications, and he's been adopting Scrum, which is the preferred approach of the Scrum partner he's now working for. 

One of the things his teams are struggling with is how and when to create documentation. 

The Agile Manifesto says, " We value working software over comprehensive documentation", but that doesn't mean we don't value comprehensive documentation at all. Especially when the software isn't working and it's up to you to troubleshoot it. 

I value documentation. I value documentation almost as much as I value working software. Not, not quite as [00:02:00] much, but nearly. 

In this episode, I'd like to share with you the documentation, my teams and customers find valuable. Then how, and when, we produce that documentation. 

My ideas about documentation might not be right for you, your teams and your stakeholders, but hopefully what you hear in this episode will spark some ideas for improvements on how your teams could work, or you could just lift my ideas up and copy them in directly, if you'd like. 

Here goes. Let's start with the documentation we create before the project begins. 

If you've been listening to this podcast for a while, taken any of my courses, seen me at a conference, or read any of my rans on LinkedIn you'll know and not a fan of analyzing requirements in advance, and documenting them in a requirement specification. 

You can throw your requirement, specification, the upfront system design specification, and your project plan Gantt chart in the recycle bin for all I care. 

Instead, I like to start with an ordered product backlog that summarizes the features that the users need and any other work we need to do to release our business app into production. That might include non-functional requirements like data migration, security testing, and project assurance reviews as well.

I don't recommend refining all the feature-sized or epic-sized stories into user stories before sprint one. Just take the first feature and refine it into user stories and estimate those a week or two before sprint one starts, so that you've got something to work with in your first sprint planning event. 

I like to compliment the backlog with a user story map that helps us visualize the backlog in two dimensions and gives us some comfort that we haven't missed out any significant stakeholders or requirements.

I don't know if you can hear any background noise, but there's a double rotor Chinook Australian Army helicopter flying just outside my window. It's a little noisy. 

If you've ever worked with Microsoft FastTrack, they have a practice that can be useful during the initiation phase before development begins. [00:04:00] It's the solution blueprint review. The example template provided on GitHub, isn't up to much in my opinion, but the questions they suggest on the Microsoft Learn site are useful topics for discussion before building your new application. 

For example, during a solution blueprint review, you might learn that you'll need to deploy an on-premise data getaway during your project to support connectivity between Power Apps or Power BI and some on-premise data sources. Business Apps teams don't usually get to punch holes in corporate firewalls. On-premise data gateways can take months to get reviewed, approved, and deployed by your networking team. So it's better to know that it's needed at the start of the project, rather than discover that in sprint 17 when you're about to go live.

So that's the pre-project documentation my teams produce: the product backlog, the user story map, and a solution blueprint. 

Next, let's talk about the documentation that developers create during sprints. 

My teams like to start work on a new user story with a practice called Three Amigos. It's a check in between the product owner or business analyst and the developers who are going to develop and validate the increment. That's usually an application maker or a professional developer and a tester. 

After the Three Amigos, once everyone's clear on their plan for the story, the tester will start writing test case to validate the increment once it's built. Usually, the analyst will have acceptance criteria and usage scenarios stapled to the story to make writing the test case quite straightforward. 

If the increment involves writing custom .Net code, the developer will start with unit tests. Those unit tests and functional test cases are a type of documentation.

The thing I like about tests is that you can read them and get an understanding of exactly how the application should behave. They're perhaps not the documentation your product owner or stakeholders will value, but other developers, and everyone who has to support, maintain and enhance your application will definitely appreciate them.

Remember the [00:06:00] saying, "Always code as if the guy that ends up maintaining your code is a violent psychopath who knows exactly where you live." Trust me, I've been part of some of the managed service provider transitions, and those companies seem to have a hiring preference for psychopaths, some even have a policy, I'm sure. 

Part of my team's definition of done is also to document the increment in a wiki. We have a page for every major feature and we create subpages for the component features. In the page, we'll include links to user stories, test cases, and related features. 

Then we'll describe how the feature works. If any future user stories change the behavior of that feature, or refactor it in any way, then we'll come back and edit the wiki page. This way, the wiki page change history is also a form of documentation. 

The wiki also includes a few pages of context, such as solution architecture diagrams, so that the whole wiki can be exported to a document or an artifact, which is often needed if your company is outsourcing the business application support to a managed service provider filled with psychopaths.

This is my as-built solution design document. I don't like to invest too much time designing the application up front because those designs are usually drawn up the start of the project, when I know least about the requirements and how we'll solve them. 

Instead, I invest more time towards the end of the project or before a release, tidying up the wiki and exporting it as the as-built solution design. 

A good as-built solution design describes how the application works, but I've never seen one that describes WHY it works that way.

If you've ever reviewed a system or read somebody else's design, you've probably wondered, "What an earth were they thinking? Why did they design it like that? Why didn't they design it LIKE THIS instead?" 'Like this,' of course, refers to how YOU would've done it in their shoes. 

A decision register is a handy compliment to the solution design. In the projects where we've kept a [00:08:00] decision register, we've got all sorts of decisions being made by different stakeholders about different topics. But the decisions we are interested in are the application design decisions. Anytime someone in the team asks, "Should we use Dataflows or Azure Data Factory?", "Can we use Power BI or do we have to use Tableau?", or even something as mundane as, "Do we prefer JavaScript or business rules?", or "Option sets or lookup tables?", your team is about to make a design decision. 

Take a moment to document it. Describe the question, the options you considered and why you chose the option you did.

If you work in the type of environment where a little bit of, uh, ass covering is a good idea, include the names of the people involved as well. 

The last type of documentation my teams create is... actually anything else the product owner asks us to. Need an acceptance test plan? Sure thing. Need a description of the security vulnerabilities and mitigations? No problems. Need an evaluation of the interesting new features coming up in the Wave 2 release? Coming right up. 

Your product owner can add a backlog item for a document or any other kind of artifact to the product backlog, order it, and ask the team to develop it in an upcoming sprint. Your product owner is accountable for guiding your team to work on the most valuable stuff. Usually that's increments of working software, but it doesn't have to be. If she needs the team to develop a document, instead of an increment, that's completely up to her. 

As developers we're welcome to negotiate and discuss whether that's really within our team's wheelhouse or not. And our scrum master should be facilitating those discussions, but it's your product owner's call at the end of the day. 

Let's just recap the types of documentation then. 

Before the project, it's the product backlog, a user story map, and a solution blueprint. 

During each sprint, we create unit tests, functional test cases, as-built feature descriptions in our wiki, and we're maintaining our decision register. 

Towards the end of the project, or before each production release, [00:10:00] we're publishing our as-built solution design to help make our applications supportable and maintainable.

And anytime we're developing whatever other documentation artifacts, the product owner adds to the product backlog. 

That's it for episode 124 of Amazing Applications. Don't forget, you'll find show notes with helpful links to resources and a transcript at https://AmazingApps.Show/124. Thanks so much for joining.

Keep sprinting.