Archive | Documentation

RSS feed for this section

You are what you document

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 …


You are what you document is a post from CSS-Tricks

MDN Product Advisory Board

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 …


MDN Product Advisory Board is a post from CSS-Tricks

The Options for Programmatically Documenting CSS

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 …


The Options for Programmatically Documenting CSS is a post from CSS-Tricks

What Does a Well-Documented CSS Codebase Look Like?

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 Does a Well-Documented CSS Codebase Look Like? is a post from CSS-Tricks

On Writing Feature Requirements

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 …


On Writing Feature Requirements is a post from CSS-Tricks