User Story Driven Docs

AlexQin

Find the Right Timing to Start Documenting

Since most development teams follow a mix of SCRUM and Kanban, they also demo the new developments after each sprint. These touch points allow us to evaluate how much the team has progressed, and check if it makes sense to start documenting and producing training materials for that new feature.

The timing must be right. If we tackle a project too soon, we end up documenting features that are prone to change. If we tackle the project too late, we risk shipping documentation late. More importantly, we risk not being able to give feedback to the development teams that might make the feature for our users.

AlexQin

Test-Drive the New Feature and Give Feedback

When we think the timing is right, we get a build from the development team and try to execute the user stories with the new features.

We implement some proofs of concept just to try and understand the best story to tell in the documentation. For example, should the documentation about fetching data from the database focus on fetching customers, orders, tickets, or something else?

After we've gathered some experience with the new feature, we also share our feedback with the development teams. This allows us to pinpoint situations that make it harder to learn and use the new feature. For instance, identify that it's not intuitive how to query data from multiple tables, understand what a specific property is used for, or understand what an error message is trying to convey.

AlexQin

Create a Documentation Draft

We then start drafting the documentation for the new feature. We usually use a collaborative writing tool like Google Docs, and avoid using markup, screenshots, or anything else that distracts us from the user story we are trying to explain.

A round of "20%" feedback is followed within our team and the development team that implemented the feature. The goal of this feedback round is to validate if we've nailed the user story and the example we're using to explain it.

AlexQin

Polish the Documentation

Finally, after we've all agreed that the user story makes sense and we've got a good narrative, we review and polish the documentation. We do some editorial work and add the necessary screenshots to ensure users get all the context they need.

An "80%" round of feedback follows. At this point, the technical details are also pinned down, so the feedback is on ensuring the documentation is compelling, easy to read, and that it properly explains how to accomplish a relevant user story.

AlexQin

What We've Learned From This Journey

Since 2012 we've learned a couple of important lessons.

Start small. Take new and smaller projects as opportunities to start changing.

It's easier to convince others to follow you, if you've got something to show. With the first documentation project we've done back in 2012, we were able to show some positive results, but this didn't create the awareness we needed to make us change.

Don't wait for major projects to start changing. After finishing the documentation for the application lifecycle management tool, I was hopping that we get a project to revamp our most used docs. The docs for our IDE. But there are always things getting in the way. So if you really want to change, start with the new features you're shipping right now. Then your changes will get some visibility and momentum, and other things getting in the way will seem less important.

Someone needs to lead the change. If you're frustrated with something don't just complain, do something.

Personally I was frustrated with:

• Documentation that didn't show how powerful and easy the OutSystems Platform is;
  
• Documentation that didn't help users connect the dots;
  
• An ever growing maintenance backlog that was stopping us from thinking strategically;
  
  

I saw how user stories could help address all these issues, so I documented a flagship feature with user stories. At the beginning, the feedback I got within the team was mostly about being inconsistent. But after a while the feedback started changing, and now documenting by user stories is the status quo.

Users Stories make us better developer advocates. After you've identified the user stories, you can leave your gut feelings aside when giving feedback to others.

User stories that are executed frequently should be easy and straightforward to accomplish, for example querying data from the database. User stories that are not so frequent can be more difficult and hidden, for example check the SQL that was generated by OutSystems Platform for fetching data.

If the development team implemented something but there's no user story for it, maybe it's just bloatware and your product is better off without it. Just this year we were able to convince the development teams to drop two features that would otherwise be included on the product but wouldn't be of use to 99% of our customers.

AlexQin

This is Only the Beginning

So far we only had experience creating user story driven documentation for the more visual parts of our product. There is still much to learn and iterate.

Maybe it makes sense to use the same approach for documenting frameworks, APIs, and other low-level aspects of the development tools. Or maybe user story driven documentation won't work at all in these situations.

Maybe there's something better than user stories, that we are yet to find out.

AlexQin

About the Author

Joao Fernandes is an Academy Engineer at OutSystems, where he is responsible for creating the product documentation, and free online training. His ultimate goal is to put himself out of work by working closely with the development teams and helping create products that require no training or documentation.