When we talk about CSS we usually forget or under-use word documentation. The primary cause of this under-use is because Documentation is not visible to end users and is most of the time is overlooked by clients. When its first time documenting code, the question of what and how become more critical i.e. what is to be documented and how to increase the effectiveness of documentation.
CSS documentation has a lot to offer for the success of a project. It contribute best for the ease of on-boarding of new member in project team. it also encourage best code practice. We would try to explain what can be done to improve the best practice to make documentation become a definite contributor for the success of project.
Developing the convention and ways for implementation.
The first step in documentation is that it should be very clear that what should be documented and how you want documentation to be worked. Therefore a convention must be developed and should be agreed upon by all the team members. The ways to implement it should also be developed and agreed upon. The agreed developed convention and methods to implement it should be communicated to each team member. It’s better that we use a live document so that everybody can contribute to it. It helps to make a comprehensive document and as all are contributing to it, the commitment to implement it is also increased among all bringing the uniformity in approach. A shared Google doc, a wiki page on your code repo, or a page on your “living style guide” is all great places for this. It is better to use “living style guide” for comprehensive documentation.
Explain the Structure of Your Code Base
People find it easy to start the work if they know the basic idea of how you organized your code. Creating a map explaining your file structure to explain what’s in it and what should go where. These people can play special attention to those places where there could be ambiguity. For instance, indicating that the file “buttons.css” contains styles for buttons is not very helpful, but indicating that the “custom” directory is where custom styles for the theme are located can be a time saver. For example
Project Root
└── srs
├── styles // Base styles. Styles placed here should be available anywhere in the application
├── bootstrap-custom // Custom styles that overwrite bootstrap
├── custom // Custom styles created for the application
├── demos // Demos to illustrate styles and interactions for the style guide
├── fonts
├── img // Images used ONLY in stylesheets
├── variables // Variables used in the custom theme
└── styles.less // Imports of all the base stylesheets
└── components
├── alerts
└── alert.less // Custom styles for the alert component. Every component has its own stylesheet that allows to customize it specifically preventing bloat and style leaking.
We suggest that wherever a clarification is required, it’s better that we document it in a proper manner. It should also be noted that some of the file and directory i.e. font in above example are self-explanatory and doesn’t need any explanation. In fact if we really want to find out what should be considered for documentation, think yourself as a layman or someone who is new to project.
Another key element to point out here is where new styles should be added and any steps that should be followed. The example above demonstrates this, but given the inheritance nature of CSS, it can be worthwhile to state it in detail.
How to establish coding standards
Coding standards or CSS style guide refers to the way your team has agreed on writing CSS. This includes the best practices on writing code, like formatting, naming, and syntax conventions. Many companies have shared the way they do it (this article from CSS-Tricks has a great compilation: CSS Style Guides). Here are a couple of ways we find it useful to share this type of information:
What are the Best Practices
Summarize your guidelines into best practices and include examples. This will make each one easier to read and understand. For example
The way one developer writes code can greatly differ from another. This is why it’s important for your team to set coding standards. This ensures that code is consistent across a project, which makes it easier to read, write and review. But make sure that anything that is included in coding standards is a practice that team has agreed on.
I worked on a project where we included this in our living style guide. As part of the code, we committed and pushed these best practices to the repo. Then to make sure everybody was on board, everybody on the team had to approve the pull request before we could merge it. This guaranteed that everybody had to make time to review and discuss it.
Stylesheets
When you break your styles into smaller and more focused stylesheets it’s easier to document them. We can also save time by not having to document what becomes self-explanatory.
For example, instead of having one 800 line stylesheet with all the variables that it can be used in a theme, We can have a file for each of the variable types. This will save time by not having to scroll up and down in the file trying to find something! Think as well of the time that can be saved by not having to update the index every time we add or rename a new section.
In a long file, a long index...
/*-------------------------------------------*\
variables.less
Index
- Color Palette
- Typography
- Buttons
- Forms
- Layout
- Messaging & Status
- General
- Navigation
- Carousel
- Jumbotron
\*-------------------------------------------*/
Document CSS With a Style Guide in Mind
A big part of documenting CSS properly has to do with writing good CSS and vice versa. This means that even when the state of CSS code base might not be the best, enforcing documentation rules can move us towards a better system.
This is where documenting CSS with a style guide in mind comes into place. The idea behind it is that a style guide can help us to determine a good structure for CSS because to create one we need to distinguish between:
the baseline styles that define the look and feel of your application (including any CSS frameworks that we are using)the customizations that are done to specific components, and the customizations that are done to specific pages.
The bulk of CSS could be comprised of the baseline styles, as they are available anywhere in the application and affect all elements in their default state. Custom styles should take place as we add components with a specific look and behavior or in the cases where the layout of an element or component in a page requires it.
Once we know how a style guide looks like in your application, we can document elements with that in mind. For example, if we have defined in our style guide how buttons and navigations look, it’s clear cut where we should add new styles and documentation for them (in “buttons.css” and “navs.css”). But what about a navigation that’s made of buttons?
Having a style guide can help us make this decision, as we can compare how buttons and navigations look, from a display and a markup perspective. Let’s look at this example:
<button type="button" class="btn btn-primary">Primary</button>
<button type="button" class="btn btn-secondary">Primary</button>
<button type="button" class="btn btn-emphasis">Primary</button>
<button type="button" class="btn btn-primary disabled">Primary</button>
<button type="button" class="btn btn-secondary disabled">Primary</button>
<button type="button" class="btn btn-emphasis disabled">Primary</button>
<ul class="nav nav-tabs">
<li class="active"><a href="#">Active</a></li>
<li><a href="#">Nav Item</a></li>
<li><a href="#">Nav Item</a></li>
<li class="disabled"><a href="#">Nav Item</a></li>
</ul>
In this case, there are two possible locations for the CSS that will define the navigation made of buttons:
If the markup follows the structure of other navigations, using a list of links, or a <nav> with links that look like buttons, then add the nav styles to “navs.css”.If the markup that you will use is <button> then, add the styles to “buttons.css”. You could even add it as a separate stylesheet (like “buttons-group.css”). In this case, the term “navigation” wouldn’t be appropriate any longer since HTML buttons are less accessible as navigational items.
Breaking Stylesheets Into Sections
Once you have broken down your stylesheets into more manageable files, then you can continue this exercise by breaking down each style into individual sections.
To begin with, each stylesheet should at least include a title and (when useful) a short description. The title could be as simple as the name of the file, capitalized to look more like a title (ex: “Buttons” for the stylesheet “buttons.css”), or it could be the same as the name of the file, like this:
/**
* icons.css
*/
.icon {
font-family: 'whizzystack';
speak: none;
font-style: normal;
font-weight: normal;
font-variant: normal;
text-transform: none;
line-height: 1;
}
I find using the filename particularly useful when debugging the code in the browser, and mostly when the file has been compiled with other files, as I can get a reference to the file where the style lives.
Also, note that the comment style that I used opens with /** vs just /*. This is a convention used in JSDoc to parse comments that should be included in the auto-generated documentation. I recommend using this style, as many living style guide generators use the JSDoc format, so when we are ready to use a generator, our code will need very little additional work.
In any case, we can use other styles to denote a section such as:
/*_______________________________________________________________*\
* icons.css
*/_______________________________________________________________*\
.icon {
font-family: 'whizzystack';
speak: none;
font-style: normal;
font-weight: normal;
font-variant: normal;
text-transform: none;
line-height: 1;
}
To some extent, this depends on what team agrees is the best way to make a section stand out. The only requirement is to use /* at the beginning and */ at the end. What really matters is that whichever approach we use, we stick to it and use it across our CSS code in a consistent way.
If you think a description might be useful in a particular stylesheet, then add it as part of this first comment. For example:
/**
* icons.css
*
* Icons should convey in a simple and meaningful way the concept of the function they represent. When designing new icons be sure to remove any complexities and follow the linear and lightweight appearance of the icon set.
*/
.icon {
font-family: 'whizzystack';
speak: none;
font-style: normal;
font-weight: normal;
font-variant: normal;
text-transform: none;
line-height: 1;
}
Doing this will reinforce the idea of it being a section. Also, try to break down the description into multiple lines (Harry Roberts recommends up to 80 characters) so that it’s easier to read while having multiple files open or while reading it on Github.
After adding a title and a description, we can go a step further by breaking down the styles within the stylesheet into sections. To do this think about how logically explaining the contents of a stylesheet makes sense. For example, the stylesheet “buttons.css” will typically have a section where the default style of a button is defined by just applying the class .btn. Then there will be additional styles that define different colors, sizes, and configurations that can be applied in conjunction to further customize its appearance and behavior. Creating sections for each of those styles will make it easier to understand and find where new classes or overwrites should appear. Also, it is less intimidating to look at a file when the code is presented in snippets versus a long file where it is hard to tell where styles begin and end.
Index the Contents of Your Stylesheets
This is a great way to provide a snapshot of what’s in the stylesheet and a must in those projects where, for whatever reason, long stylesheets are there to stay (not a fan of those projects, but they do happen!).
A stylesheet index typically looks like this:
/**
* icons.css
*
* Icons should convey in a simple and meaningful way the concept of the function they represent. When designing new icons be sure to remove any complexities and follow the linear and lightweight appearance of the icon set.
* Index
*- Icon Font
*- Icon Variations
* - Icon Animations
*
*/
And although how neat and useful they can be,it has to be admitted they can be easily forgotten, and therefore outdated. They are also a pain to update when they are long and we are using numerals (so avoid those!)
An alternative way of using indexes is to let a style guide generator do the work for us by looking at our stylesheets, finding the sections that we have defined and generate an index for us. I will expand more on this topic at the end of this article.
Find the Sweet Spot of Documenting
Here is where the secret of documenting lies. It’s easy to get carried away and go into a documentation frenzy once, to then forget about it and end up with only a portion of our codebase over-documented and the rest undocumented. As with everything in life, the secret is finding the balance. Document those areas where attention is needed because there are unforeseen dependencies, additional resources, or important notes to have in mind. That is to say that not every bit of code should be documented but it is definitely useful to break it down into chunks and explain what those chunks are when necessary. In this way, documentation becomes a useful tool that is part of our workflow and not an afterthought that we avoid to do. But how do you exactly do that?
What can be the next step?
One step further is to incorporate a living style guide as a part of documentation. A living style guide is a living document that shows a comment which is included in code structured like a website, so you can navigate the documentation separately from the source code.
What makes living style guides powerful is that the actual documentation lives with the code and can be easily updated as our code changes, allowing it to stay in sync and relevant. The additional advantage is that we can make this documentation available to other people on our team who might not be interacting directly with the code (like designers, product managers, or QA engineers). These team members would also find it helpful to know how the UI is shaping up.
In a living style guide, we can include interactive demonstrations of our code and we can further organize our documentation independently from the code structure.
Conclusion
Documenting CSS begins with clear rules and a well-structured code base. When done as part of our workflow, it can also serve as a guide to structure our code and keep it organized as it grows. This has the additional benefit of making it clear where things are and where new code should be added, easing the onboarding of new members while fast-tracking development.
Comments