Markdoc

Came across Markdoc today, made by Stripe.

Stripe is know for its excellent developer documentation – well it has to be, its probably the most important feature for the company. If you go through their documentation is not just a good reference guide, but they also allow you to interact with it to get a feel on how to use the API effectively.

Stripe built their own content authoring system and have now released this as an open source project. It supports Markdown which makes it a joy to use this tool. The tool looks great too.

The tool is so easy and pleasing to use, that I have been using this to simply write my notes 😊

What’s in a Good Error Message?

I came across this great article by Gunnar Morling and have been wanting to repost this for a while… better late then never.

So what makes a good error message then? To me, it boils down to three pieces of information which should be conveyed by an error message:

Context: What led to the error? What was the code trying to do when it failed?
The error itself: What exactly failed?
Mitigation: What needs to be done in order to overcome the error?

The reason I find this article get is cause its coming from a Software Developer keeping other developers in context. I have worked as a Product Manager & a UX professional for several years now and Error messages is one of those areas which does not get much attention.

Its always at the back of your mind but other important aspects take over and error messages typically get overlooked.

Good error messages are important. When things go wrong, these error messages are the only communication channel between your software and customer. A good error message will allow your customer to recover well or submit a support ticket – and thats $ we are talking about.

The first comment by RossVertizan on this blog also has an important aspect for good error messages:

One thing that I would add is an indication of severity. Personally, I like to have every message preceded with a word which indicates the severity of the message

Things to read for Week 44

Github gets a new CEO

GitHub CEO Nat Friedman is stepping down from his role on November 15 to become the Chairman Emeritus of the Microsoft-owned service. Thomas Dohmke, who only recently became GitHub’s chief product officer, will step into the CEO role.

Great to see a product person stepping into the shoes of a CEO.


Tesla is letting non-Tesla EVs use its Supercharger network for the first time

Tesla’s Supercharger network is often held up as the best possible example of an EV charging network: fast, reliable, and plentiful. But Tesla’s network is also exclusive to Tesla owners, meaning someone driving a Volkswagen or Ford EV wouldn’t be able to use it. But that’s now starting to change.

So how long until we start hearing about standardized car chargers?


How to design a good API and why it matters:

If you find yourself in charge of building an API for your application and need a good reference, this is a great start.


Toxiproxy

Toxiproxy is a framework for simulating network conditions. It’s made specifically to work in testing, CI and development environments, supporting deterministic tampering with connections, but with support for randomized chaos and customization.

This is a good library to have in your arsenal whether you are an Engineer, PM or QA. Testing on different network conditions is important.


Why you should develop a UX roadmap:

Thinking ahead to next quarter, consider collaborating with your fellow designers, researchers, and content strategists to develop a UX roadmap. This will prompt you to review potential work against user and business goals and prioritize the most important items. From there, you can share your draft with key stakeholders and see if they agree. Developing and refining this roadmap will help you become more strategic and focused, while helping you develop your collective perspective and voice.

Its not easy to change the culture of how things are built. It’s hard but its important to start doing this.


6 things a Product Manager is not:

4. A product manager isn’t an agile fascist

Agile and lean are all-the-rage and de rigueur in modern software development. The next statement will probably be an unfashionable one but agile isn’t the only way to build web products and waterfall isn’t evil. Product managers shouldn’t be wedded to cult agile.

This made me chuckle. Good read.


First companies and now cities battling for top talent. Good times.


Prioritize health over work. It’s important.

One more gadget: The Ember Mug 2

Coffee is probably one of the most ubiquitous and social products in the world. I’m sure tea is also somewhere right up there. So it doesn’t hurt to say a Hot Beverage.

I have seen messy desks (I have one) and extremely clean ones and a mug for a hot beverage is ubiquitous. One of the things that drives me nuts is the rate at which my beverage goes from pipping hot to stone cold. It’s not that I am lazy to get up and heat it – its the fact that every time I wake up i have the urge to make a fresh cup of hot beverage to replace my cold one. I hate wasting food.

I’m sure there are studies that would say Coffee/Tea is good or bad for your health. For me apart from Coffee being a fuel it helps me be alert (especially when you are in those long and boring meetings), it has certainly helped me improve productivity (also proved by this MIT study).

Earlier this year I was diagnosed with Cervical Radiculitis – a pathological condition of the spine and one of the reason for this was my sitting posture. It’s hard to maintain a good posture when you work in front of a screen for more than 12 hours a day. It’s even harder to correct a habit that is ~30+ years old. A hot beverage allows me to stretch back, straighten my poster and take a nice hot sip. Doing this every 20-30 minutes helps tremendously.

So when Ember came out with their temperature control mug, it was a no brainer to get one of these.

Ember has a travel mug and a regular mug. Personally I prefer the mug.

They come in 2 sizes, 10 oz and 14 oz. To put it in perspective, the 10 oz although small looks like a normal mug that’s available in the market. The 14 oz mug – although they do have that extra 4 oz; stand out cause the shape and size is not like any other normal cup available in the market.

Also remember these mugs come with a batter – which is typically heavy, so the more bigger you cup, the much heavier it gets. I went with the Black Ember Mug2 10 oz size.

I generally prefer the black color, but when it comes to utilities, I do prefer white. There was one reason I chose the Black Mug – Coffee Stains. These mugs are made of durable stainless-steel with a ceramic reinforced coating (presumably food grade) which gives these mugs the nice matt finish. And this finish will retain coffee stains. I’m sure the black mugs also retains coffee stains, but they are barely visible.

The App

The Ember Mug comes with an app. Following the instructions and I was able to pair this mug with my phone in less than 30 seconds. That was awesome.

It also walked me through to create a profile that allows me to choose a coffee brand, brew style, and my desired temperate. They suggest 135 F to being with; after setting this temperate for a week, i reduced mine to 132. Personalization is a great thing. The app also comes with multiple presets for different kinds of coffee brews.

The overall app is OK. Not the best usable app. The main screen is basically a screen with a single color and a number that shows your current coffee temperature in the middle and at the very bottom an animation showing how far off it is from your desired temperature and your profile if it’s selected one.

The ^ right below the animation suggests more options, and every time instead of tapping it, i swipe up and close the app. When you get there, you can select a coffee preset, or add/remove presets; a Tea timer if you need one, and some coffee recipes. I have never used this page after the first setup.

Settings
The settings screen allows you to:
1. change the color of your LED – I set mine to green
2. Adjust brightness (of the LED maybe?)
3. shows the Battery level
4. Change Temperature – I have mine setup at Fahrenheit
5. Notifications – I turned mine on to notify me when my coffee reaches the right temperature.

Menu
The menu has a lot more options. I enabled Ember X Health and every once in a while when I’m thinking what exactly this app does, I venture into insights.

The LED Indicator
One of the things that has always confused me is the LED indicator on the mug. It flashes Red when the battery is running low or out of charge. Most of the time it is white; and I’m have seen it go Green only when its on my charging plate. Basically IO have absolutely no idea what these indicators mean. For now I think or it as the mug has battery and its working.

Conclusion

So far its the best $99 that I have spent this year.

It keeps my coffee at my desired temperature. The battery on this lasts long enough for me to take my mug and walk around or go to a hour long meeting. Because of the ceramic coating, they do feel fragile, but I’m assuming the stainless-steel makes it durable. The confusing LED indicator – try and tune out of this and think of the white light as the mug’s working.

iPad Pro gets a trackpad

iPad Pro was announced this week with a load of Hardware goodness.
But what got the most attention was that iPad Pro now has a trackpad. Well, the Magic keyboard did (not the iPad) and the iPad OS was updated to support the trackpad.

You can always get the regular Magic Keyboard too.

Steve Sinofsky on the iPad Pro getting a trackpad:

2/ Hardware evolves just like software but we don’t often see it the same way. We’re used to talking about the cycle software bundling and unbundling, but hardware does the same thing. Every new generation of hardware begins this cycle anew.

Users change, they way the interact and interface with a piece of hardware also changes over time. What apple is doing great here is that they are keeping the medium intact for users who want it to work the way it should as well as introducing changes for new users and their behaviors.

And why is a trackpad so important to some users – give a listen to this episode on The Talk Show with John Gruber and Federico Viticci.

And after all of that, just head to apple.com and watch the video and look at the beautiful piece of hardware(s).

Documenting UX

A lot of companies today implement an agile process and the remaining ones like to call themselves agile. A few years back any designer (UX/IX) would pull out their hair because turning around design details wasn’t easy given the amount of time a sprint would end. Years go by and processes have evolved. Processes like LeanUX and staggered sprints or design and R&D sprints in parallel have more or less solved this issue. However these processes have reduced the amount of documentation.

We have user research data, but never used it to create personas. We have analytics data but never exported them out of their software/databases. There are a list of scenarios or stories that are important or have a higher priority, but they never made it to the official todo list or backlog. All, I see is wireframes, trolls of em. Some of them make sense like login screens and forgot passwords; the others I have no idea. Today wireframes have become one of the most important means of documentation. I even see scanned sketches, photographed whiteboards and clickable wireframes. One change in the use case or workflow, and you are back to square one.

It does capture details; however, chances are when I see someone else’s wires, I may not like a solution. How do you support your solution? 

And I have made them all; mistakes. The fact that the requirements or priorities are in my head and not anywhere else does not do good for me to convince someone why these things need to be done the way I intend to. 

Over the last couple of months I started maintaining a combination of few documents that has helped me transition stuff and propose design easily. Here is a short run down of these documents and processes: 

We all do our bit by venturing out and talking to users. We capture notes and lot of em. When you do so, try to capture them as quotes. There are two important advantages in doing so. One, Its faster to write them while you are interviewing/talking to them and Two, it preserves the context. 

“I have to apply the same filter every fucking time I visit this page” 

“See I like this pages concept in OneNote. This way I can just have multiple notebooks and go and write down in pages within them…”

One of the important thing is to digitize these notes. It could be in a notepad or Evernote; I found excel helpful (yeah!). I was able to create buckets/categories and then write the quotes in these specific buckets. Also, when I digitized these notes; I was able to add attributes to them; like screen resolution, position, firm, interview date, system usage, type of user, etc. These become important when I really wanted to narrow down to specific kind of users.  Apart from that I color codeed these quotes – for example. Red for negative, Blue for positive and Greens for opportunities; this gave me an idea on the state of the existing software.  

I haven’t created any personas (and I might not for the time being) for my work. But when I was working on a specific problem, I was able to filter down to a handful of target users in my excel sheet then parsing through notebooks of research data. Once I have narrowed it down to a bunch of users, it is easier for me to identify patterns in their quotes (colors added value). Those attributes that you add now allows you to see how much is in common between these users.

After looking at my excel, I note down tasks/use cases/stories. I maintain a list in a todo list. Apple reminders does the job for me. Nothing fancy. This allows me to scope out, prioritize stuff. Anything that is high priority gets a date and bubbles up, rest of them just remain at the bottom. Simple.

Analytics – If you have it, great. This comes in use when you really want to see what users are doing with existing systems. How are they using it. Export them and keep them handy. Don’t rely on your system that you did log in and get data. Historic data is fine. Patterns are not going to change overnight. Export them because you can quickly pivot data. That is important to figure out supporting numbers for your uses cases. 

This accompanying my wireframes/sketches is a good combination. I try to ensure my wireframes are also not too elaborate. Stick to the specific workflow or use case and thats good enough. 

Trying to Keeping iSimple and Stupid. So far it has worked for me. Maybe over the next few months or a year I will know if it was effective enough.

Please leave your comments and suggestions or any of the processes you personally follow or send an email to get in touch.