In about a month I'll be presenting at Write the Docs 2015 (yaaaaaaaaay!). I'll talk a bit of our experience at OutSystems, trying to create user story driven documentation.

And here is a sneak peek of my presentation.

I'm Joao Fernandes, and I'm an Academy Engineer at OutSystems. My team and I write the docs, create our free online training, and do a bunch of other stuff to ensure our platform easy to use.

At OutSystems, we create a platform that allows enterprise customers to create mobile and web apps in a visual way. You model the data, design the pages, and implement the logic in a single IDE and we take care of most non-functional requirements, like logging, security, and scalability.

I'll talk a bit of how we stopped trying to document the UI, and started creating awesome user-story driven docs. We now try to focus on what the user wants to achieve and how to achieve it, independently of how many windows or buttons they need to go through.

A clear example of this, was that we had a full documentation page for the find text feature (CTRL+F). It described in excruciating detail every option available on the UI:

• Case sensitive, case insensitive;
• Only match whole word;
• Refine the search scope.

We focused on documenting these self-explanatory options, but didn't told our users how they could find what they need:

• How to find all elements with a given name;
• How to find all CSS rules affecting the headings;
• How to find all queries to a specific database table.

In this talk I'll tell you the how we stopped trying to document the UI, and started delivering user story driven documentation.

I'll cover:

• Why you should avoid documenting the UI;
• How you can check if you're currently documenting the UI;
• Why users stories might be better a better way to document a product;
• How focusing on user stories changed our team's culture, and allowed us to work on what really matters.

Join me in beautiful Portland, Oregon at Write the Docs 2015 to learn more!