Recently I was on-boarded into a project with more than 1,500 pages of documentation written in\u2026 Microsoft Word. It was outdated and unorganized. A real disaster. There must be a better way!<\/p>\n
I’ve talked about this documentation issue before. I scratched the surface not long ago here on CSS-Tricks in my article What Does a Well-Documented CSS Codebase Look Like?<\/a> Now, let’s drill down into the options for programmatically<\/em> documenting code. Specifically CSS.<\/p>\n <\/p>\n Similar to JSDoc<\/a>, in the CSS world there are a couple of ways to describe your components right in the source code as It’s sometimes argued that a development approach focused on documentation is quite time-consuming. I am not going to disagree with that. One should always strive for a balance between building functionality and writing docs. As an example, in the team I’m currently on, we use an agile approach to building stuff and there are blocks of time in each sprint dedicated to completing missing docs.<\/p>\n Of course, there are times when working software trumps comprehensive documentation. That’s completely fine, as long as the people responsible are aware and have a plan how the project will be maintained in the long run<\/strong>.<\/p>\n Now let’s take a look at the most popular documentation options in CSS:<\/p>\n KSS<\/a> is a documentation specification and style guide format. It attempts to provide a methodology for writing maintainable, documented CSS within a team. Most developers in my network use it due to its popularity, expressiveness, and simplicity.<\/p>\n The KSS format is human-readable and machine-parsable. Therefore, it is intended to help automate the creation of a living style guide.<\/p>\n Similar to JSDoc<\/a>, in KSS, CSS components are described right in the source code as comments. Each KSS documentation block consists of three parts: a description of what the element does or looks like, a list of modifier classes or pseudo-classes and how they modify the element, and a reference to the element’s position in the style guide. Here’s how it looks:<\/p>\n Benjamin Robertson describes in details his experience with kss-node<\/a>, which is a Node.js implementation of KSS. Additionally, there are a bunch of generators that use the KSS notation to generate style guides from stylesheets. A popular option worth mentioning is the SC5 Style Generator<\/a>. Moreover, their documenting syntax is extended with options to introduce wrapper markup, ignore parts of the stylesheet from being processed, and other nice-to-have enhancements.<\/p>\n Other sometimes useful (but in my opinion mostly fancy) things are:<\/p>\n Who knows, they might be beneficial for some use-cases. Here’s an interactive demo<\/a> of SC5.<\/p>\n Unlike the JavaScript world, where JSDoc is king, there are still a bunch of tools that don’t use the KSS conventions. Therefore, let’s explore two alternatives I know of, ranked based on popularity, recent updates and my subjective opinion.<\/p>\n If you’re searching for a simple, concise solution, mdcss<\/a> could be the answer. Here’s an interactive demo<\/a>. To add a section of documentation, write a CSS comment that starts with three dashes The contents of a section of documentation are parsed by Markdown and turned into HTML, which is quite nice! Additionally, the contents of a section may be automatically imported from another file, which is quite useful for more detailed explanations:<\/p>\n Each documentation object may contain a bunch of properties like title (of the current section), unique name, context, and a few others<\/a>.<\/p>\n Some other tools that have been on my radar, with very similar functionalities are:<\/p>\n Nucleus<\/a> is a living style guide generator for Atomic Design<\/a> based components. Nucleus reads the information from DocBlock annotations.<\/p>\n Atomic Design is a guideline to write modular styles, projecting different levels of complexity on a (bio-) chemical scale. This results in low selector specificity and allows you to compose complex entities out of simple elements. If you’re not fairly familiar with Atomic Design, the learning curve may look a bit overwhelming in the beginning. The entities for Nucleus include:<\/p>\n The button example we use throughout this article here stands for an Atom<\/strong> – a very basic element of the stylesheet (single-class element or selector). To mark it as an Atom, we need to annotate it with the \/* comments *\/<\/code>. Once code is described through comments like this, a living style guide<\/strong> for the project could be generated. I hope I’ve stressed enough the word living<\/strong> since I believe that’s the key for successful maintenance. Based on what I’ve experienced, there are a number of benefits to documenting code in this way that you experience immediately:<\/p>\n\n
Knyle Style Sheets (KSS)<\/h3>\n
![\"\"](\"https:\/\/i0.wp.com\/css-tricks.com\/wp-content\/uploads\/2017\/07\/styleguide_screenshot.png?ssl=1\")
<\/figure>\n\/\/ Primary Button\r\n\/\/\r\n\/\/ Use this class for the primary call to action button.\r\n\/\/ Typically you'll want to use either a `<button>` or an `<a>` element.\r\n\/\/\r\n\/\/ Markup:\r\n\/\/ <button class=\"btn btn--primary\">Click Me<\/button>\r\n\/\/ <a href=\"#\" class=\"btn btn--primary\">Click Me<\/a>\r\n\/\/\r\n\/\/ Styleguide Components.Buttons.Primary\r\n.btn--primary {\r\n padding: 10px 20px;\r\n text-transform: uppercase;\r\n font-weight: bold;\r\n bacgkround-color: yellow;\r\n}<\/code><\/pre>\n\n
![\"\"](\"https:\/\/i0.wp.com\/css-tricks.com\/wp-content\/uploads\/2017\/07\/primer.png?ssl=1\")
MDCSS<\/h3>\n
---<\/code>, like so:<\/p>\n\/*---\r\ntitle: Primary Button\r\nsection: Buttons\r\n---\r\n\r\nUse this class for the primary call to action button.\r\nTypically you'll want to use either a `<button>` or an `<a>` element\r\n\r\n```example:html\r\n<button class=\"btn btn--primary\">Click<\/button>\r\n<a href=\"#\" class=\"btn btn--primary\">Click Me<\/a>\r\n```\r\n*\/\r\n.btn--primary {\r\n text-transform: uppercase;\r\n font-weight: bold;\r\n background-color: yellow;\r\n}<\/code><\/pre>\n\/*---\r\ntitle: Buttons\r\nimport: buttons.md\r\n---*\/<\/code><\/pre>\n![\"\"](\"https:\/\/i0.wp.com\/css-tricks.com\/wp-content\/uploads\/2017\/07\/mdcss.png?resize=300%2C264&ssl=1\")
<\/figure>\n\n
Nucleus<\/h3>\n
\n
@atom<\/code> tag, followed by the name of the component:<\/p>\n\/**\r\n * @atom Button\r\n * @section Navigation > Buttons\r\n * @modifiers\r\n * .btn--primary - Use this class for the primary call to action button.\r\n * @markup\r\n * <button class=\"btn\">Click me<\/button>\r\n * <button class=\"btn btn--primary\">Click me<\/button>\r\n * <a href=\"#\" class=\"btn btn--primary\">Click Me<\/a>\r\n *\/\r\n.btn--primary {\r\n text-transform: uppercase;\r\n font-weight: bold;\r\n bacgkround-color: yellow;\r\n}<\/code><\/pre>\n![\"\"](\"https:\/\/i0.wp.com\/css-tricks.com\/wp-content\/uploads\/2017\/07\/nucleus.png?resize=300%2C286&ssl=1\")
<\/figure>\n