Style Documentation for the Resource-Limited

by Betsy Haibel

The video titled "Style Documentation for the Resource-Limited" features Betsy Haibel from ActBlue discussing practical strategies for creating effective style guides under resource constraints. The talk emphasizes the importance of clear goals and achievable steps when documenting UI components, while recognizing the challenges of interdisciplinary collaboration in web development.

Key points discussed in the video include:
- Defining Goals: Establishing a clear vision is essential to avoid aimless progress.

- Breaking Down the Process: Any project, especially under limited resources, requires breaking it down into manageable tasks, while being realistic about time allocations.

- Flexibility and Adaptation: Recognizing that plans may evolve over time and being open to changes in the vision is crucial.

- Use of Examples: The 18F style guide is highlighted as a successful model due to its alignment with specific needs instead of an oversized template like Google's Material Design.

- Accidental Style Guides: Existing codebases often serve as unintentional style guides due to consistent copy-pasting practices, which may falter as teams grow.

- Documenting UI Components: Betsy outlines a three-step process for developing a style guide that includes identifying UI components, codifying them in code, and then documenting them to enhance team collaboration.

- Iteration over Perfection: The speaker stresses that documentation should not be treated as a one-time project but rather evolve incrementally, drawing parallels with Agile principles in software development.

- Tools for Documentation: Utilizing tools like Hologram and KSS for creating visual documentation that can link functionality to design is advised to ensure clarity and enhance communication between developers and designers.

In conclusion, Betsy asserts that effective collaboration through proper UI documentation is achievable, advocating for incremental improvements, clear communication, and maintaining a flexible approach in the development journey. She invites the audience to explore additional resources for code samples and documentation techniques shared in her talk.

00:00:09.860 Welcome to the style documentation for the resource-limited. My name is Betsy Haibel.

00:00:15.540 Today, we are going to talk about ways to create style guides in the real world, as opposed to the idealized scenario where you have three months to stop everything and work solely on this.

00:00:28.380 Whenever you're working under resource constraints, creating a style guide or anything else requires following some basic steps. First off, you need to have a goal. Without a clear vision of where you want to go, you will end up going back and forth and fiddling around aimlessly.

00:00:41.610 Second, you need to break down the process into manageable baby steps. It's essential to be realistic about what you can accomplish in these steps. Often, you will overestimate how much you can get done in any given time frame. For instance, if you're planning to devote 20 minutes a day to this task, think about what you can truly achieve in that time.

00:01:07.490 Moreover, remember that circumstances will change. If you're setting aside only 20 minutes a day, but your teammates are working on coding for much longer than that, you need to adapt to this shifting scenario. The vision you start with is great; it keeps you motivated and focused. However, you must accept that the end result may not match that initial vision—what you ultimately produce may end up being even cooler.

00:01:39.150 Now, let's look at a specific example: the 18F style guide. 18F is a division of the US government, and I find it to be an excellent example of an effective style guide. 18F comprises several small teams that consult for other government agencies. Unlike Google's Material Design, which is designed for large-scale companies, 18F offers a more realistic approach that is better suited to our specific needs.

00:02:22.560 We often talk about the importance of aligning our business logic, where developing a shared, ubiquitous language with stakeholders is vital. However, we also need a distinct shared language for our user interface logic. In web development, we distribute this user interface logic across HTML, CSS, and JavaScript. Keeping this organized is not easy due to its distributed nature. A coherent model allows us to manage this complexity.

00:03:00.210 Interestingly, you already have an accidental style guide: your codebase. All of your forms likely look similar. This consistency is usually achieved through a liberal use of copying and pasting. This approach works well in a small team or with a limited UI, but as you scale, it becomes trickier. You begin to onboard newer developers who may not know what to copy and paste or what the correct parts of this accidental style guide are.

00:03:43.920 Rails provides structures for organizing your business logic, but not everyone has a clear visual structure for their code. Every codebase has its own quirks, which can create transparency issues. Additionally, stakeholders—especially designers—will often have strong opinions about the results of views compared to business logic since the user interface is tangible and easy to comprehend. Thus, it's crucial to focus on creating a coherent model for the user interface.

00:05:10.560 When discussing user interface concepts, it's important to differentiate between various context uses, such as card modules. Designs should go beyond basic branding guidelines. Many say they use Helvetica and stop there, but a comprehensive style guide can delve into the specifics of widgets, including their affordances and aesthetics, as well as how they’re arranged. Questions arise, like, 'Are labels next to the form fields or above them?' or 'Where do error messages go?'

00:06:31.670 A style guide should also address which problems a particular widget can solve, providing guidance like, 'Use carousels to display several card bits, but otherwise, just use a grid,' or 'Only display notifications relevant to the user’s current task.' When done correctly, this end result will resemble Bootstrap documentation, but you may think that this is overkill. The term 'just using Bootstrap' can often signal an underlying issue.

00:07:01.740 If you think your team is merely using Bootstrap, consider these questions: Are you using all of Bootstrap, or just a subset? Are you only using Bootstrap, or do you have custom UI elements? Do you have undocumented bits of code or rules around using Bootstrap elements? If you find yourself answer yes to any of these questions, your style guide may not align with Bootstrap documentation.

00:08:05.909 Documenting deviations from Bootstrap is crucial and doesn’t have to be fancy. Simple annotations with links to further documentation can suffice. However, there are other barriers to style guide adoption beyond just the question of 'Why do we need this?' These include perceptions of it being a lot of work or feeling restrictive in flexibility if built rigidly.

00:09:16.489 Additionally, if a style guide is viewed as a one-time project and assumed to represent a fixed standard, it risks becoming just another set of dead documentation that drifts away from the current realities of development. All software embodies a combination of love and duct tape, and we all know that incremental improvement is the way to success.

00:10:34.050 Over the last 15 years since the Agile Manifesto, we’ve embraced the concept that our software is never fully complete; likewise, our documentation must remain flexible and responsive. I've previously worked with a style guide that was beautifully designed but fell out of date quickly after a lead designer left, leading us into a dilemma of whether to halt progress for a migration to a new style guide that also may not be relevant to users.

00:11:39.489 When we view the creation of such guides as a perfect versus worthless proposition, we demotivate ourselves down a path of inaction. History has shown that iterative processes yield better results than attempts to be perfect or doing nothing at all. Engaging with brownfield test suites, which involve wrapping tests around uncovered code, is akin to building out a style guide incrementally. Initially challenging, it becomes easier as the tests and documentation start inflating the structure and usefulness over time.

00:13:15.330 Approaching documentation in a similar iterative manner allows us to sidestep various problems, maintaining a velocity while enhancing the style guide incrementally. Each small improvement builds credibility within the team about why this effort is worthwhile. Addressing the dead documentation issue must be solved early in the process to encourage collaboration.

00:14:51.990 I’m going to outline a three-step process for establishing a style guide that involves identifying UI components, codifying them, and documenting them. Step one: identification is straightforward; assess your application by comparing the UI elements side by side. Look for patterns, such as common card layouts or tabs, and focus on common components first.

00:15:57.670 Once you've identified these components, the next step is to codify them in code. Refactor your existing code to enforce internal consistency, which sets the scene for effective documentation. You can’t sell this idea to the team as a magical solution; instead, clearly demonstrate how a few improved lines of code can offer tangible benefits to their work.

00:17:14.800 Moving on, while this part of the talk shifts into the code, I'm hopeful you can focus on the overarching concepts rather than getting bogged down in the specifics. Most slides will highlight key areas of interest for you. In the concluding part, I will provide a link to a blog post that includes all the code samples presented today for your reference.

00:18:33.860 The process starts with refactoring. For instance, in a Rails project, you would use a helper to simplify the code structure. By placing comments above method names that illustrate the HTML output, it enhances readability and helps designers who may not be familiar with Ruby.

00:19:59.750 As you refactor your UI code for better organization, create a parent class to encapsulate the concept. This may simplify future iterations. Although sometimes you might find your components are complex, creating nested helpers or achieving abstraction can help clarify the intended use and improve maintainability.

00:21:17.210 Your component builder ultimately encompasses initialization, rendering, and collections of sub-renders. Keeping the initialization lightweight while focusing on generating markup via sub-renders will streamline the process. Use comments effectively to make sure the markup generated is clear and thus aids readability.

00:22:48.490 Once your components are built and organized, you can utilize a tool to document them. Documenting your style guide is effortless due to the code comments you’ve created during your CSS file documentation. Using tools like Hologram also makes inline documentation more manageable, allowing for automatic updates that require minimal maintenance.

00:23:47.350 However, your documentation needs to communicate effectively with designers and stakeholders, which can be achieved through various platforms. It’s important to find ways to prioritize relevant information for your style guide, ensuring it encapsulates both developer-centric and designer-centric views.

00:25:12.960 Thus, the essential elements of your minimum viable product for documentation should highlight pictures of UI components alongside example code. While additional descriptive use cases may enhance clarity, it is not necessary for the first iteration of the project, emphasizing the need to avoid burnout during implementation.

00:27:21.410 Tools like Hologram for Ruby projects or KSS for JavaScript-heavy frameworks can facilitate this documentation process. The output can display happy visuals alongside functional code samples which engage more effectively with your audience. Even if you venture into more complex integrations with your helpers, it's okay to start simple.

00:28:43.750 The ideal outcome involves both rendering the HTML and showcasing the helpers for these components. Designers can rapidly prototype using your actual style primitives, enabling a collaborative approach. Importantly, there will be occurrences where designers will create prototypes using these guides that allow developers to implement them efficiently.

00:30:12.960 Ideally, working with a sound style guide fosters effective communication between designers and developers. It diminishes miscommunication or yelling in project management tools, as you both have references to consult and collaboratively refine the user experience, eventually leading to a pleasant working culture.

00:31:58.110 In summary, achieving effective collaboration through appropriate UI documentation is a reachable goal. Understand building blocks of UI, utilize abstraction wisely, and maintain communication throughout the process. Your path may be unique, but with these guidelines, you’ll reach the utopia your team deserves.

00:33:33.700 Here’s a link to the blog post containing code samples as well as another blog post that provides guidance on setting up Hologram with Rails effectively.

00:34:04.759 Thank you for your time; my name is Betsy. You can find me online enjoying whimsy, my cat, science fiction, and code-related discussions.

00:34:10.730 I work with ActBlue, a tech organization focused on fundraising for Democrats. We play a crucial part in amplifying smaller donor contributions in a meaningful way.

00:34:30.888 I would like to thank everyone for their feedback on early versions of this talk, contributing to its quality. Are there any questions?

00:34:37.159 Absolutely! I will tweet out the link right after leaving the stage. ActBlue is headquartered in Massachusetts, but we are remote-friendly. I have found that more of our colleagues are remote rather than in-house, and it's a fantastic remote culture.

00:36:08.619 Thank you all for being here!