• Skip to primary navigation
  • Skip to main content
  • Skip to primary sidebar

Dion Almaer

Software, Development, Products

  • @dalmaer
  • LinkedIn
  • Medium
  • RSS
  • Show Search
Hide Search

Software Development

Does mobile documentation matter for developers?

July 9, 2019

Developers code on their laptops, normally docked with their mechanical keyboards and monitors, right?

As such, when it comes to developer documentation, you don’t need to be responsive, and can focus on a desktop-only set of docs.

I have heard this sentiment many times, and at first blush it makes some sense. For all the talk of mobile eating the world, a lot of the business end of things happens on the desktop Web.

Once you have desktop docs going, you look at your stats and see that you were right! A fraction of traffic is coming from mobile! Glad you didn’t waste any time on a great responsive experience! Well, hold your horses. You may have self selected your answers here.

A great developer experience includes a great documentation experience, and that includes mobile. I have seen transitions from desktop-only to responsive, as well as responsive from day one, and both have shown how important it was to go mobile, too.

Take one of the Google developer sites for example, and a recent slice:

mobile: 90+% of share
This slice is from a campaign, so bias, but directionally similar

Why is mobile such a big deal?

All documentation isn’t equal. There are a variety of reasons why someone ends up in your docs. The Web is a viral platform due to the sharing of URLs through all sorts of mediums (via Email, Twitter, Slack, etc). People are increasingly accessing these mediums via mobile, and are tapping in to read from there. I often read a lot of developer-oriented content on mobile, and will save it away and often revisit on desktop.

I also do a lot of memorization through mobile, using space repetition systems. A common task during the day will be saving some developer knowledge into my system.

This is somewhat akin to customers who browse for products on mobile and finish the transaction on desktop.

Beyond documentation

It has been fantastic to see the trend of developer documentation being seen as putting the manual online with some hyperlinks, and instead using the medium to add a lot of interactivity to help you learn.

The best way to learn is to do, and it is important to be able to feel how things work and play with them. We have embedded Glitch into web.dev as an example of bringing you tight playgrounds to explore, and remix for your own experimentation.

How do you want this type of content to be approachable on mobile vs. desktop?

The other important realization for me has been integration. Developers often end up in your docs via search, and they rarely probably go to your root domain and just read read read.

Take time to look in the Search Console to see your analytics to see how users are getting to you, and make sure that you have the content they need. You need a base of reference documentation, and then can walk up the chain to use cases, and finally verticals.

Look for other areas of integration.

  • Where do your developers live?
  • Their IDE? And certain plugins?
  • Do you want to reach them on StackOverflow or Glitch?
  • Do your error messages link out to documentation to help?
  • Do your docs work offline? (e.g. if someone is reading on the subway to work, or generally stuck in poor and variable connectivity)
  • Do you include code from source files that you have tests running against to make sure that a copy paste works?
  • Have you built a connection between the tools and your documentation so it can be surfaced inline?

There is so much to do, and while “docs” are a first class citizen, it is also important to recognize that good tech writers are still under-rated!

render() your consciousness

February 20, 2018 Leave a Comment

I recently woke up, remembering a dream that tied together the following:

  1. how does our consciousness surface a certain subset of the huge amount of input that is processed in the brain?
  2. how can we best handle all of the events in our computing systems, and render a UI that represents a valid state?
  3. how can we build a UI representation that helps users, with their consciousness, actually get something useful done?

It wasn’t shocking that I had this dream, given that I fell asleep listening to Anil Seth as a guest on Sam Harris’ podcast, which I turned on right after coding.

When we write programs that model the world, one of the areas that we often struggle with is the notion of representing time, and how state changes over time. It is a source of many bugs, and has lead many to look toward immutable state as a way to avoid foot guns. Rich Hickey famously explains his experience on the topic in Are We There Yet?


How our consciousness batches time

When you zoom in with concurrency and time, you get into the notion of something happening at the same time. At first blush this is a simple concept, but when you look deeper at how our consciousness deals with this, it is fascinating. As we get new tools to probe the brain, we are uncovering a lot of new information, such as learning that decisions have been made before you thought you made them.

Simple experiments show the layers of filtering and input changing that occurs. If you touch your finger to your nose, it always “feels” like the touch happens at the same time for both digit and nose, yet your arm is longer than your nose. Inputs from the nerves must reach the brain at slightly different times at therefore at some point they get put together as a batch.

It appears that our component systems are getting masses of input that we are processing, and there is competition for the right level of info to reach our consciousness. We can direct things at times (e.g. we can take control of our breathing, but fortunately don’t have to focus on it to always happen) but mostly we are observing and our consciousness is revealing what has happened.

Back to programming

This shares some similarity with painting the right UI for our users (and vsync). We can gather information from our components, batch together the state, and prioritize what to render. With the appropriate amount of complexity in our state, especially considering the difference between app state and UI state, it may make sense to use a system such as Redux to manage the batching, or maybe you prefer TJ’s state management library https://twitter.com/tjholowaychuk/status/957853652483416064.

Elsewhere, it is common to debounce, sometimes with exponential backoff, to make sure we aren’t wasting a lot of time and resources.

https://github.com/joshwcomeau/redux-vcr

Immutability also has huge side benefits. We can save snapshots that enable improved testing and time travel debugging. Also, any excuse to bring back a VCR is surely a win 😉

Using the past to change the future

Having snapshots of state is one thing, but what about using old states to help you in the now? While we often save past state snapshots, we don’t often use them in rich ways to help change future state, but your brain does just that. Experiment after experiment shows the importance of context.

This video shows how you can be primed to see color in a black and white photo. There are examples of this across our senses. You can listen to some audio that sounds like gibberish, hear key words, and listen to it again and suddenly you understand the gibberish.


Examples of illusions fill books, and are what magicians use to trick our senses. This all makes me wonder if we are going to see richer ML models that help the user based on the past context?

Good UI is magic

A lot of this trickery feels like magic and illusion. This is absolutely true, but great UI is jam packed with this type of illusion. We can use motion and progressive rendering to make it feel like things are happening, keeping the user engaged. We can make sure to prioritize which parts of the UI to update and delay on others.

To do this correctly, often requires you to take the time to map out the SLO of various pieces. For example, when you visit an e-commerce product page, show the core information asap, and wait on data below the fold such as reviews. You should also consider the freshness requirements across these elements too (e.g. the price has to be fresh, but you don’t need to block on that new review!).

I am having a lot of fun learning about how the brain works, and our psychology, and have a feeling like this knowledge is going to be useful for our industry as we get better at delivering UI that truly helps our users consciousness understand the view of the world that matters to them as they get done what they need to get done.

Oh, this sounds like a good excuse to watch Darren Brown explain the tricks of the trade: mentalism, cold reading, neuro-linguistic programming, cognitive illusions, and much more.

Isn’t building software products fun?

Plan to serve cup cakes at your software wedding

January 18, 2016 Leave a Comment


The wedding ceremony is past and your tummy rumbles. The food at these events is somewhat hit and miss as it isn’t easy to feed this many troops. Chicken or fish? Hopefully the cake will save the day! At some parties as of late the decoration may be traditional, available for the cut and face smash, but we all for cup cakes.

It was this memory that fired whilst thinking about software that setup the analogy that you should consider shipping cup cakes vs. large wedding cakes.

The wedding day is your ship date for a major release. As time goes by you need to make adjustments to the schedule.

You may have a suites of products all working to come together, or you may have a series of features in a release. You don’t want them all relying on each other to create that one spectacular cake. With a cup cake approach you can have differing types that come together on their own schedules.

Your users don’t know the plan

I can’t tell you how often I have seen the following happen, falling for this bias myself. You build your plan and although everyone is running hot to ship the entire cake you all kinda feel like it would be wiser to focus and cut. But how can you, the cake will be so delicious! If you don’t have some of the ingredients it won’t reach its potential! We quickly forget that the users don’t know the plan and would probably prefer a cake with some ingredients missing, if the quality of the pieces we do ship is higher.

If something shows up half arsed it is obvious, and sets the tone. It may be enough to turn off a user who may never come back.

With be One Big Cake there are ingredients you can’t just skip else it will taste bad, but with cup cakes you could offer fewer options and no one would know. You need to be crystal clear on which is which, and say no to the items that aren’t critical ingredients.

Having come from the world of retail where shipping features in February has an insignificant impact compared to October, it is crucial to play this game well. You can’t move the holiday season, so you need to plan accordingly.

In general though I am a huge fan of the flywheel. Chrome is a perfect example of this. The trains run on time and a process helps the progression of features from ideas to canaries to beta to stable. New cup cakes show up every six weeks.

As you plan the narrative of how you are making your users bad ass in 2016, remember that they don’t know the details that you know, so allow for a flywheel of quality rather than risking the Big Bang of meh.

Next Page »

Primary Sidebar

Twitter

My Tweets

Recent Posts

  • The holy grail of a Web SDK
  • The rise of the extensible app platforms
  • Active Recall now out of beta and open for all learners!
  • Agency developers are underrated
  • Web Developers are Shopify Developers

Follow

  • LinkedIn
  • Medium
  • RSS
  • Twitter

Tags

3d Touch 2016 Active Recall Adaptive Design Agile Amazon Echo Android Android Development Apple Application Apps Artificial Intelligence Autocorrect blog Bots Brain Calendar Career Advice Cloud Computing Coding Cognitive Bias Commerce Communication Companies Conference Consciousness Cooking Cricket Cross Platform Deadline Delivery Design Desktop Developer Advocacy Developer Experience Developer Platform Developer Productivity Developer Relations Developers Developer Tools Development Distributed Teams Ecosystem Education Energy Engineering Engineering Mangement Entrepreneurship Exercise Family Fitness Founders Future Gender Equality Google Google Developer Google IO Habits Health HR JavaScript Jobs Jquery Kids Stories Kotlin Language Leadership Learning Lottery Machine Learning Management Messaging Metrics Micro Learning Microservices Microsoft Mobile Mobile App Development Mobile Apps Mobile Web Moving On NPM Open Source Organization Organization Design Pair Programming Paren Parenting Path Performance Platform Platform Thinking Politics Product Design Product Development Productivity Product Management Product Metrics Programming Progress Progressive Enhancement Progressive Web App Project Management Psychology Push Notifications pwa QA Rails React Reactive Remix Remote Working Resilience Ruby on Rails Screentime Self Improvement Service Worker Sharing Economy Shipping Shopify Short Story Silicon Valley Slack Software Software Development Spaced Repetition Speaking Startup Steve Jobs Study Teaching Team Building Tech Tech Ecosystems Technical Writing Technology Tools Transportation TV Series Twitter Typescript Uber UI Unknown User Experience User Testing UX vitals Voice Walmart Web Web Components Web Development Web Extensions Web Frameworks Web Performance Web Platform WWDC Yarn

Subscribe via Email

Enter your email address to subscribe to this blog and receive notifications of new posts by email.

Archives

  • June 2022
  • May 2022
  • April 2022
  • March 2022
  • February 2022
  • November 2021
  • August 2021
  • July 2021
  • February 2021
  • January 2021
  • May 2020
  • April 2020
  • October 2019
  • August 2019
  • July 2019
  • June 2019
  • April 2019
  • March 2019
  • January 2019
  • October 2018
  • August 2018
  • July 2018
  • May 2018
  • February 2018
  • December 2017
  • November 2017
  • September 2017
  • August 2017
  • July 2017
  • May 2017
  • April 2017
  • March 2017
  • February 2017
  • January 2017
  • December 2016
  • November 2016
  • October 2016
  • September 2016
  • August 2016
  • July 2016
  • June 2016
  • May 2016
  • April 2016
  • March 2016
  • February 2016
  • January 2016
  • December 2015
  • November 2015
  • October 2015
  • September 2015
  • August 2015
  • July 2015
  • June 2015
  • May 2015
  • April 2015
  • March 2015
  • February 2015
  • January 2015
  • December 2014
  • November 2014
  • October 2014
  • September 2014
  • August 2014
  • July 2014
  • June 2014
  • May 2014
  • April 2014
  • March 2014
  • February 2014
  • December 2013
  • November 2013
  • October 2013
  • September 2013
  • August 2013
  • July 2013
  • June 2013
  • May 2013
  • April 2013
  • March 2013
  • February 2013
  • December 2012
  • November 2012
  • October 2012
  • September 2012
  • August 2012

The right thing to do, is the right thing to do.

Dion Almaer

Copyright © 2022 · Log in

 

Loading Comments...