This is a refactoring where an example task goes through rounds of iteration, improving the design with commentary.

Our goal is to create a service for sending email. We need a set of options that fit into two sets:

The most difficult part of any design process can be finding the correct, best, or most successful idea out of all possible ideas out there. In User Experience (UX) we start by finding empathy with the user, researching user preferences, successes and failures, and understanding the needs of the clients. However, even armed with research and understanding, discovering or uncovering the correct solution out of all the possible solutions out in the world can still be problematic. Used appropriately, sketching is a fantastic way to generate new ideas without the usual constraints we put on ourselves with technology.

The heart of creating a LSG is the ability to put your documentation right where it belongs: in the source code. Chances are that you are already documenting your code, which is a great opportunity to take it to the next level by using a style guide generator that can turn those comments into an organized site, letting others (and yourself from the future) know why and what has been done in the code.

While the bulk of your LSG documentation will come from special comments that you add to the source code, you can also create standalone pages where you can host other types of content that are not specific to the code (think of design principles, accessibility guidelines, or pull request guidelines). This gives you the advantage of centralizing your documentation in one place: your application living style guide.

Imagine this: you’re a designer who has been tagged on a pull request as a reviewer. It’s up to you to look at the changes made and decide if you are going to approve them and let them frolic with the rest of the app code.