Does mobile documentation matter for developers?

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:

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!

One browser to rule them all?

Sizzy is the latest custom browser for a particular niche, this time design. Blisk is another that targets developer use cases. Ironically, it’s tagline is “One browser to rule them all” when, in fact, maybe it paints an alternative picture.

Time for an Eclipse

I remember a trip that Ben and I took to Ottawa. It was in the winter, and happened to occur at the same time as a visit from Obama (so, you know, in the good old days ;). We were visiting the core team at IBM behind Eclipse (and SWT and OSGI and ….) such as Steve Northover. The topic was web based IDEs, since we were working on Bespin and they were building Orion.

They were great to talk too, because they have so much experience in the world of tooling, having worked on them for decades.

One of the lessons I learned was that Eclipse was originally a foundation. If you look at the layers: SWT as a native widget toolkit, OSGI as a way to dynamically modularize, and Eclipse as the IDE bits…. you had a way to customize and build an IDE. Maximum flexibility.

But many Java developers downloaded Eclipse and used it. Many appreciated it, but many also found it far too confusing (Perspectives?). The IDE platform was being used as the end product. Since then, custom IDEs have been build with Eclipse, using the power of the platform but delivering a custom and opinionated view for it’s users.

I reflected on this as I played with niche browsers and wondered….

What if we had more browsers in our lives, not less?

What most think of as their “browser” is the Web platform with a product surrounding, and integrating with it. The main feel of the browser hasn’t felt that different for awhile. You still see the URL bar up top, still use tabs, etc.

A browser expected to be baked into an operating system, but we still see new browsers looking to innovate and find their own niches, such as funding models and verticals. So far, the browser itself feels familiar.

Unless you consider the “app browsers”. The apps that deeply embed the Web as a core part of their experience, such as Twitter, Facebook, Google’s Search app, and on and on. These have taken a particular view that is less of a blank slate that allows you to put in a URL (well, or search, or leap from a new tab page that has a feed too… ok there is some innovation there!).

Imagine how a browser would be different if it was oriented in a particular way? E.g. a developer browser that didn’t focus on speed for users, but on getting you as much data to help you debug and develop?

Just as with Eclipse, there are many ways to get there. You can customize through plugins, or you can have a seperate distro that is fully setup and ready.

It does make me wonder though…. can we find a new bar that allows for much more innovation in the product space, while we all work together to push the web platform forward, in a way where developers can ship to reach as many users as possible.

What would you like to see?

The Truth about Web Components and Frameworks

Have you noticed that there is a regular community.nextTick() that involves heated discussions around “Web Components vs. Frameworks” in some form or another.

It can be frustrating to see the same topics repeatedly pop-up, but I find it interesting to dive into why it does so.

A pattern I often see is a tension where we want to reduce a topic to a simple black and white abstraction, but when we fail to do so, we bounce off to fight another day.

Reductions and Abstractions

We are pattern matchers, and predictors of the future at our core. Much of our progression as a species has been in building up abstractions that allow us to model the future. So, it isn’t surprising that we try really hard in science and engineering to find abstractions.

Often science and math give us a purity of abstraction, whereas engineering has us in the complex muck where we hunt for patterns that are hiding in the world of a massive number of variables.

Early abstractions start out leaky. As we climb to the next level we need an escape hatch to where we are safe and knowledgeable. How much assembly was written in the early years of C vs. today?

Over time, if an abstraction is solid, we will be able to basically ignore a layer, at least in the main. There are a huge number of programmers that have never learned the assembly layer, and the machine layer below. Some may bemoan this at times, but if an abstract is good, many will get by.

NOTE: I still think it is optimal to understand one layer below (and one above if applicable!) as Glenn used to say..

How does this relate to Web Components and Frameworks?

Right! I contend that we are in a messy state of abstractions not being clean here, and the desire to find black and white is hitting up against the world of grey.

The simple to understand views are these:

  • Web Components lost and are unnecessary. Just use the component model in your framework of choice!
  • Web Components are all you need. <Components> all the way down baybee!
  • Use Web Components for UI leaf nodes, and an app framework to glue it together…. it all just works!
  • A company should only allow one framework to be used, and thus reuse is at that framework level!

In the real world, one of these could be true for one form of truth, but they miss all of the nuance and ignore many other forms of truth, such as:

  • For many apps, simple orchestration using Web Components, beyond leaf nodes is fine
  • For many apps, it is overkill to build reusable Web Components, and that’s fine
  • It is rare to see a company (of size) keep every application on the same version of the same framework, and this approach has many many trade offs
  • Sometimes companies buy other companies, and they come with code and legacy
  • It’s ok to experiment with new frameworks and new paradigms, it’s how we progress
  • Web Components aren’t the only way that you can share code, and that’s fine
  • Gluing between component models isn’t fun, but it’s also fine
  • There are very different roles. If you are a vendor of components you will think very differently about how you scale the component set and who you want to target

We can go on and on and on. It’s messy, and it can also work. The environment is changing around us (browser support, evolving libraries, new paradigms such as the recent “compilers”).

I think it is only a good thing for the platform to give us a way to define <our-components>, and I love seeing the interop change over time.

But at the end of the day, what I care most about is that we can be productive, and our ecosystem has content that users love (which includes, but isn’t solely subject to, performance… have you setup performance budgets?).

Do we have all of the components we need to move fast? Tooling? Can we fix bundling to not be a nightmare for developers?

If we can honestly look at ourselves and feel like we are doing the right thing there, the rest is gravy.

It’s OK living in the gray. It’s OK not having worked out the perfect abstractions, yet.