documentation Archives

You are what you document

# January 2, 2018 By Robin Rendle

There are so many little gems in this piece by Yevgeniy Brikman all about documentation. He digs into a lot more than simply documenting code though and focuses on how we can document every phase of our work, from design to process and beyond.

Here’s my favorite lines that made me sit back and shout “Wahoo!”:

When a developer uses your code, they are really learning a new language, so choose the words in it wisely.

...programs must be written for people to read, and only incidentally for machines to execute.

I like how Yevgeniy suggests that there are kinda two different mindsets that we have to get into when writing code: one for making the dang thing work in the first place, and another for explaining how and why we did a specific way. There’s context-switching that takes place between those different stages of work.

Anyway, when seen in this light, documentation could be much more than a nice-to-have. Instead, it might just be 50% of the work.

documentation

MDN Product Advisory Board

# October 19, 2017 By Chris Coyier

We all know and love MDN for already being the best documentation for web features out there. It looks like it's poised to get even better with Google and Microsoft both joining a new board.

Mozilla's vision for the MDN Product Advisory Board is to build collaboration that helps the MDN community collectively maintain MDN as the most comprehensive, complete, and trusted reference documenting the most important aspects of modern browsers and web standards.

Interesting none of them mentioned WebPlatform, the previous attempt at this that kinda fizzled out. This effort seems a little more likely to succeed as it already has a successful foundation, actual staff, and a benevolent dictator in Mozilla. It's great to see browsers complete on user features but cooperate on standards and education.

Worth a shout that we dabble in "docs" for CSS features ourselves here at CSS-Tricks with the Almanac, but if anything in there is worth taking for a unified resource like MDN, be our guest. Not to mention everything public on CodePen is MIT, and there are loads of Pens that demonstrate web features wonderfully. For instance, that's why I built this one.

documentation

The Options for Programmatically Documenting CSS

# July 6, 2017 By Kaloyan Kosev

I strongly believe that the documentation should be kept as close to the code as possible. Based on my experience, that's the only option that works well in the long term. External documents, notes, and wikis all eventually get outdated, forgotten, and lost.

Documentation is a topic that always bugs me. Working on poorly documented codebase is a ticking bomb. It makes the onboarding process a tedious experience. Another way to think of bad documentation is that it helps foster a low truck factor (that is, "the number of people on your team who have to be hit by a truck before the project is in serious trouble").

Recently I was on-boarded into a project with more than 1,500 pages of documentation written in… Microsoft Word. It was outdated and unorganized. A real disaster. There must be a better way!

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? Now, let's drill down into the options for programmatically documenting code. Specifically CSS.

(more…)

What Does a Well-Documented CSS Codebase Look Like?

# June 20, 2017 By Kaloyan Kosev

In the front-end community, there is a lot of attention related to documenting JavaScript. That's not so much the case with CSS. Often times I feel like lost when I join a project with minimal or no CSS documentation.

Even though CSS is relatively easy to write, it can be quite hard to maintain. The specificity, the global scope of everything, and the lack of guidance can easily lead to inconsistency, code duplication, and over-complication.

I've long been curious what a really well-documented CSS codebase looks like. Here, I'll share my experience, along with the expectations I have towards my vision of well-documented stylesheets.

(more…)

CSS documentation

On Writing Feature Requirements

# March 29, 2017 By Geoff Graham

I have been asked to lead product development on a team. This is somewhat of a new journey for me because I'm generally used to calling myself a web designer rather than a product manager or strategist.

The toughest part of this job for me has been organizing my thoughts. I've written an executive summary for the product we're building, done some competitive research and even dusted off my limited MBA education for a SWOT analysis. Oh yeah, now it looks like I know what I'm doing!

Many of us who read CSS-Tricks with any sort of regularity likely have to think strategically to do our jobs, whether it's in design, development, or both. What I've found, however, is that thinking strategically is a whole lot different than acting strategically. (more…)

documentation strategy