Upcoming event:

I'm giving an API documentation workshop in Los Angeles, California, on January 23, 2020. Check it out on EventBrite.

Input needed:

I'm gathering data about trends in developer documentation for 2020. If you write docs for developers, please take this survey. (You can view the ongoing results here.)

Hiding Complexity -- A new Simplifying Complexity article

by Tom Johnson on Jun 12, 2018 •
categories: simplifying-complexity

I added another article in my Simplifying Complexity series. This one is called Hiding complexity through JavaScript show/hide elements. The basic principle is to look for ways to reduce complexity by hiding less-used information on the screen through JavaScript techniques, such as show/hide elements, expand/collapse toggles, and more.

Here’s how the article begins:

While troubleshooting a recent support case, I looked over documentation I’d written nearly a year ago, trying to identify where the user got stuck. I was shocked at how confusing the docs now seemed. The documentation tried to explain query syntax for targeting elements in a media feed that could be either JSON or XML. If the feed was JSON, developers would use one type of query syntax; if the feed was XML, they would use another. The documentation discussed the two approaches in sections one right after another.

This scenario is common in developer docs because you often have multiple languages to account for. You might have a process for calling an API that you need to explain using PHP, Java, .NET, or other languages and frameworks. The general approach might typically be the same, but the code samples and specific technical details will differ….

Read the rest: Hiding complexity through JavaScript show/hide elements

Search results

Hiding Complexity -- A new Simplifying Complexity article