DEV Community: Ryan Haber

Hacking Back the Meeting Jungle

Ryan Haber — Thu, 15 Apr 2021 15:05:45 +0000

Product managers go to a lot of meetings. I know devs often do, too. The number of hats a product manager wears is one cause that adds to the meeting load.

This is important: We often accept unthinkingly the number of meeting and the amount of time spent in meetings as proxy measurements for effective collaboration. This situation arises when we don't know how to measure outcomes. Individually, we tolerate being involved in so many meetings - even when we don't know why we're in them - because on some level we feel them to indicate importance.

This has to stop.

I don't know how I would survive without blocking off 2-3 hours daily of focus time. These times aren't for administrative tidbits - that happens in the little bits of time between meetings. These 2-3 hour blocks are sacrosanct and I decline meetings scheduled for me during them because I need them to accomplish the reading and thinking involved in strategy-level work and solving hard problems. These problems require what Cal Newport calls deep work, and deep work requires concentration, and concentration requires time.

At first, coworkers didn't get it, but eventually they started respecting them and even doing likewise. My blocks tend, right now, to be mornings before my West Coast colleagues come online.

Additionally, once I'm ramped up and onboarded, settled into a role, I question every meeting I am pulled into if I do not understand my role in it. I ask the organizer what, specifically they expect me to contribute. What takeaway will I have that I cannot get from the meeting notes? If they do not have a clear, specific answer, I make a deal with them: I will use the time block for getting my own work done, but I'll keep myself available in case they need to pull me in.

See what I did there? I allow their meeting, which I decline to attend, stay on my calendar and shield me from other meetings.

😁

You're welcome, Internet.

When people question either action (blocking or declining meetings), I just tell them the reason. If they plead or cajole, I smile, act sympathetic, and repeat the reason.

The great thing about this approach is that you never have to announce it or get permission. You can just start doing it. Your individual coworkers will just start understanding. You can decide to exempt certain coworkers (say, your boss) if that seems more prudent overall. Additionally, it will let you work out your negotiation skills when people start whining and you need to make them feel good while still defending your time. I recommend Never Split The Difference by Chris Voss to improve that skill set.

This is my third company using this basic approach. It works and I expect it to work here. Because I manage in these ways to keep almost half of any given day meeting-free, I produce quickly enough that I think people don't question my how. This production is part of how I produce good results.

I Made My First Simple Little API

Ryan Haber — Sun, 28 Feb 2021 19:24:42 +0000

Food Orders API

This is a gross and horrible little API that works. You can run it on your machine pretty easily.

You're not allowed to judge me because I'm not an engineer and I never claimed to be one. 😬😄

I'm just hacking around to up my game. I'm gonna keep hacking away to make this better, clean up some of the horror, and maybe eventually host on Heroku, but for now, "Look, Mom! No hands!"

Photo by Keagan Henman on Unsplash

Status Reports Made Easy

Ryan Haber — Sun, 24 Jan 2021 20:16:32 +0000

Briefing as To-Do List

When working on high-profile project, you usually have to manage a lot of stakeholder communications. They want updates on their schedule, and that doesn't always land at convenient moments. This added work us a pain and can add a lot of overhead. Several years ago, an excellent manager gave me some tips on how to harness these expectations of rapid communication and turn them to my advantage by making me look like a rockstar without creating a lot of extra work. I built on his tips and have since used the following approach to get company leadership “off my back” while not adding a ton of overhead to my life. The original approach was for a multi-faceted project with a number of stakeholders who all wanted info. The approach can be adapted for briefing not only on the progress of multiple facets, but also for situations like briefing on the work of multiple teams, etc.

Key Ingredients You'll Need

Text or Markdown files in a folder.

Package the briefings as a text file. In my original iteration, I used text files. Since then, I've started using markdown files. Same diff, basically, except markdown obviously gives a bit more visual structure in many viewing environments. Having it in a separate file in a dedicated folder makes it easy to start each day's briefing by copying the previous day's. Or weekly. Whatever.

Dedicated Channel

Each day or week or whatever, drop the briefing each day at a set time in a dedicated channel, like a Slack channel made for the purpose. Put nothing else in the channel and encourage conversation to stick to threads. This creates a channel that looks like this.

A BLUF Approach

The BLUF (Bottom Line Up Front) heading is crucial. Mine headings usually read something like, “Project on track without delays or overages.” When there was a delay, “Project progress slipping by 1-2 days, expect to recover. Inside for details,” or when a milestone was hit, “Website template accepted by all stakeholders. Project on track…"

The BLUF heading is very important because it’s what Slack shows in its text file preview. A good rule of thumb is to always put most important messaging in the most visible place. You can help people find what they need and skip the rest by making your content easily scannable. This means organizing the paragraphs into thoughtful, coherent topics with good headers and very selective keyword highlighting. This approach is good for saving busy execs time while giving them the peace of mind they need and you want them to have. My execs loved this format because it allowed them to quickly check to see if they cared to read deeper.

Good Headers

Inside the text file, I had a header for each facet of the project, as well as for any new things that had come up. Beneath the header, a similar BLUF approach with more details.

Steps to Make Your Life Easier

This approach doesn't add any or much burden for me since I began using those headers as my daily must-get-done list, even if “get done” just meant checking in with someone for an update on their piece, and then putting back in my briefing “checked in for an update… status is still the same.”

I always start the day’s briefing as a copy of the previous day’s. This helps keep things from getting left off.

When new facets arise, as I mentioned, they get new headers. Generally, once a topic starts getting a header, I always include a header for it thereafter, even if the text beneath the header stays “no change, see update of 2021-01-14 for last report”. This helps people late to the game know where to go to find what they care about.

Myself, I would only eliminate a header only once it was well and truly obsolete.

When the whole project is done, you can archive the channel for posterity to read.

When to Use This Approach

I, and my of you, my dear readers, will already have your own task management system of choice. I like Remember the Milk for personal matters and for work, whatever my company uses. Adding on another layer of task management will always create more overhead and more room for actions to get logged in one system but not in another.

A single source of truth is key. To maintain a single source truth, I switch to the system described above when I get into a high-stakes, high-visibility, communication-heavy phase of a project or time of year.

An advantage of this approach over, say, Trello, is that it allows me to control and summarize communication without opening my task management software to well-intentioned fumbling or misreading of a situation. In cases where I am managing or tracking a team with a number of tasks, I continue using Trello or some such tool to keep the team organized. I request team help in maintaining that, and I make sure my daily briefings accord with what is reported in Trello.

Quest To Get Out of the Google Trap, pt 1

Ryan Haber — Wed, 02 Dec 2020 17:18:06 +0000

I'm working to get some of my life out of the Google Trap. I'm starting with email. It seems like there are the most choices.

There's protonmail.com. I have a subscription already and I like the privacy-first approach, but am not happy with the small storage size. It's a 5 gig limit, and I'm paying like $120/yr. You can only get that up to about 50 gigs. The only solution to this cap is to download photos and upload them elsewhere, which is maybe tedious, but also maybe will help me be more thoughtful. I am excited by their forthcoming protondrive.

Right now, I'm experimenting with hey.com email. I like that larger storage size and some of their workflow features. Some of it is new enough that I'm not sure what I think.

Has anyone used either of these or another smaller, privacy-first email provider that they like and recommend?

What's Most Important When Picking an API?

Ryan Haber — Tue, 18 Aug 2020 20:39:59 +0000

Hey all, when you are picking an API, provided it's your choice and money is no option and assuming they all scale well, have great uptime promises, low latency, and no known security issues, which of the following following factors matter most to you? Feel free to add your own.

Fast / easy signup
Time to first hello world
Quickstarts are easy and intuitive
Tutorials
Accompanying tools (like a debugger, a dashboard)
Sandbox environment to playtest before you "buy"
API follows standards / best practices that you recognize
Documentation (thorough and clear)

If you want to add extra thoughts as to why, you get bonus points. :D

Thanks!

Customizable APIs?

Ryan Haber — Tue, 18 Aug 2020 20:33:23 +0000

Hey All,

I've met some of you - my background is designing, testing, and supporting APIs - and now technical product management. But I'm not gonna pretend I'm an amazing expert. I just bumped into a question and I can't find an obvious answer. I'm relaying the question here in hopes that one of my engineering betters (that's you):

has thought of it before and can point me to a resource,
thinks it's a crazy, nonsensical question and can explain to me like I'm five,
thinks it's a really intriguing question worth thinking through.

Here's the question:

Is there such a thing as a per-application customizable API?

The more I think about it, the more I think, yeah, sure, that can make sense. A REST API might be "customized" - when you create objects in Salesforce for instance, you can later access them by endpoints determined in the course of creating the objects. Each deployment of Salesforce will have its own set of endpoints.

And then not all APIs are REST APIs. And RPC might be "customized" by a config file passed to it, for instance.

I'm kinda just brainstorming here. But is this ignorant, crazy talk?

What I've Been Up To

Ryan Haber — Mon, 13 Jul 2020 02:16:45 +0000

In many respects, I know this isn't a big deal, but I do like to toot my own horn every once in a while. I'm fairly technical for a non-technical person. I was a computer science major for 3 years back in the late '90s. I worked in non-tech work from then until about 2006. From that time, I've learned HTML, CSS, Javascript, and then a few years later, Python. I'm not an engineer, but I do lots of little scripts: ETL scripts, bash scripts, data cleaning, cron jobs, etc. I'm not an engineer, but I sometimes joke that I play one on TV.

As I move into more technical product management, I realize the importance of really, deeply understanding the work I am engaging engineers to do.

Lately, I've decided to undertake some projects and tutorials to help me level up my technical skills. I don't want to understand these concepts abstractly, but as tactile realities.

So lately I have:

Set up a Lightsail instance and a load balancer on AWS
Used AWS Route 53 to configure DNS settings
Deployed a Ghost CMS (one of my favorite) blog to the instance
Started learning the basics of Flask to build a simple set of REST API service
Set up a MongoDB instance so I have someplace to store and fetch data from for my little service

Anyway, I know these aren't rocket science level accomplishments, but I'm pretty happy with what I've been up to the last few weeks.

(Photo by Bernard Hermant on Unsplash)

Review: Managing Oneself

Ryan Haber — Wed, 24 Jun 2020 14:59:00 +0000

tl;dr: Peter Drucker's Managing Oneself is a brief but seminal work that every young professional should read. By reading it and applying its principles, you will learn to manage yourself and so need to be managed by others less.

Drucker's book has seven chapters. Drucker digs into them with respect to understanding and managing oneself. My experience is that the more someone is able to manage oneself, the less one's manager usually feels the need to manage one. I will also reflect on how each question can be used to help you understand your manager, coworkers, and reports so that, inasmuch as they may need it, you'll be able to manage them.

What are My Strengths?

Drucker starts with the observation that people mostly misunderstand their own strengths, which is problematic because we do not succeed using our weaknesses, but by using our strengths. To counteract this tendency, Drucker proposes the feedback analysis. The feedback analysis is accomplished by writing down a key decision as you make it, and recording with the decision what you expect the results to be. After a suitable period - typically on the scale of months to a year - review your decision and your expectations against what actually happened.

The feedback analysis is not only a powerful means of identifying your strengths, but also of building on them. While you can mitigate your weaknesses, the cost to turn them into strengths is probably prohibitive. Just work to take the edge off your weaknesses so that they don't drag you down - but really, focus on your strengths.

Drucker also encourages his reader to identify intellectual arrogance. This often takes the form of thinking to oneself, "If I don't know it, it must not matter much." Engineers think design is easy. Designers think code just writes itself. Salespeople think UX experts are fussy. You get the idea. His advice is to knock it off.

Knowing the things that I am good at and the things that I am not good at has helped me to volunteer not for responsibilities that sound exciting, but the responsibilities that I can execute very well. This in turn has helped build my reputation within my organizations. Appreciating others' strengths has helped me to appreciate them. Everybody likes to be appreciated and we naturally like the people who appreciate us.

How Do I Perform?

"Too many people work in ways that are not their ways, and that almost guarantees nonperformance."

The above statement, in my experience, accounts for much workplace frustration. How many of us are managed by managers the way the manager likes or the way the manager thinks we need, but not the way that empowers us to knock it out of the ballpark every time. Additionally, if we've only ever been managed in ways that go against our own grain, we might never have learned which way our own grain goes.

What does Drucker mean, exactly? Well, he asks us to consider some questions. These in turn, help us get a sense of what he means by "how I perform".

Am I a reader or a listener?
How do I learn? Common examples are by reading, by listening, by writing, or by talking things out.
Do I produce results mainly when I'm a decision-maker or when I'm an advisor? This doesn't necessarily reflect one's "proper" role in an organization, mind you. A CEO might make an "executive decision" by giving good feedback to his executive team and then empowering them to decide.
Do I work well under stress, or do I need lots of structure and predictability?
Do I work best in big organizations with lots of resources or small ones with lots of improvisation?

Drucker strongly and repeatedly advises against spending too much effort to change oneself in this regard. Say writes that our personal answers to these questions tend to be deeply ingrained. We'll spend our effort better by changing our locale rather than trying to be a better auditory learner.

While I don't argue with Drucker's thrust, I will add that I have had some success. Years of listening to audiobooks for work and pleasure have made me a decidedly better auditory learner. That said, doing, writing, and talking are definitely still the ways in which I most easily learn new systems and concepts.

Knowing this about myself has helped me manage myself and, by extension, need less management. When I was younger, a boss my tell me to do X, Y, or Z. I would forget in minutes. That must have been annoying for my managers. Now I take notes or send an email/IM confirmation of our discussion. Not only does this approach help cement my learning, but it also gives me something to rely upon if I later have to account for what I've understood.

What are My Values?

By values, Drucker explicitly states that he does not mean ethics. Ethics is a part of a value system, he says - the part that doesn't change from person to person or situation to situation. Drucker is talking about other things we individually or as a group will value, setting aside purely ethical considerations. He gives the example of a company that does not promote from within because it prefers "bringing in fresh blood." The policies of preferring to promote from within versus promoting from without reflect deeper values. You can have a policy that strikes a middle ground. But these opposing policies that can be forged into a compromise at best, reflect deeper values. One policy speaks to a value of collective memory, of organic development, of developing ones existing employees. The other speaks to innovation, eagerness for radical departures, or perhaps the need for new thinking and new people. Clearly, if you value climbing a corporate ladder, this company is not the place for you.

Here's Drucker's key insight along these lines:

"To be effective in an organization, a person's values must be compatible with the organization's values. They do not need to be the same, but the must be close enough to coexist. Otherwise, the person will not only be frustrated bu talso will not produce results."

Here's my list of some of the opposing values that are important to different people and organizations. Note, because we've set aside ethical considerations (so lying to customers is straight out, or should be), these values aren't better or worse than their opposites. In fact, each value-and-opposite-value pair is usually a balancing act, and the one we prefer is often a matter of necessity or context.

process vs outcomes
stability vs adaptation
speed vs thoroughness
frankness vs cautiousness
empathy vs accomplishment
dependability vs entrepreneurship

As you learn about the values that matter more to you at some point in your life, also consider which values seem to matter more to your coworkers and the organization as a whole. These considerations may shed light on sources of any exhaustion or frustration that you experience at work.

Where do I Belong?

Drucker writes that as we get to know our strengths, how we perform, and what we value, it should become clearer to us where we do not belong at the very least.

It is important for us to know which opportunities for us to seek and which to decline.

Then he writes something that may shock many readers:

Successful careers are not planned. They develop when people are prepared for opportunities because they know their strengths, their method of work, and their values. Knowing where one belongs can transform an ordinary person - hardworking and competent... - into an outstanding performer.

If Drucker's claim is even half-true, then knowing the answers to these questions takes on an enormous importance for one's career.

What Should I Contribute?

While Drucker starts this section by stipulating a simplistic view of the 1960s and social change around career expectations, he makes other good points. His key gist is that we should not look to our employers to plot out a career path for us. In my experience, there is at least a whole generation of office workers who feel jilted because they were passed over for a promotion; rather than seeking the promotion elsewhere, out of a sense of insecurity or perhaps a false sense of loyalty, they stay at their employer. In the fullness of time, they are often passed over again.

Employers don't do this to be mean. They do it because math is harsh. If you have a team of eight people, only one can be the manager. When the manager goes elsewhere, her role may be filled internally, but only one of the remaining seven can take the role. The others are passed over. It's just math. The company has to pick the person that they think will be best for the role: seniority, experience, skill, expertise on the team aren't the only or even most important factors for picking someone who can coordinate the team to produce results. A passed-over employee, meanwhile, feels treated unfairly, given his seniority, experience, skill, and expertise, often thinking he knows why the old manager was bad, but never really developing the skills to make himself into good management material, and never taking the perceived risk of looking outside the company for that promotion.

If you want to shine, you need to contribute what the broader team needs. When you do this, people will notice not only your contributions, but your ability to identify real needs. Look for the intersection between the accomplishments your career needs and the results that your company needs. This is the making of a manager.

Drucker points out, mind you, that these kind of plans don't usually work out if they are planned in too much detail or too far in advance. Go for results that are visible and especially for results that are measurable.

Responsibility for Relationships

Another key insight starts this section:

Managing yourself requires taking responsibility for relationships.

In my experience, this insight is especially true when the other party to the relationship is unable or unwilling to take responsibility for him- or herself. The most universal example is relating to a child. The child cannot take responsibility for their share of a relationship, so adults must do so for the child: providing explanations about what is or isn't fitting in a situation, encouraging good conduct, and discouraging bad conduct.

Here's a secret I've learned. Most 'adults' are emotionally about 16 years old. A mentor of mine told me that folks stop growing up when they start insisting to others that they are grown up. We usually start telling adults to shove off when we are in adolescence. The good news is that if we will seek out mentors and admit that we still have useful things to learn, we can start getting more mature again.

When dealing with bosses, employees, and coworkers, if you really want to shine, you must learn to take responsibility for your part of each of those relationships, and often, to help them with their share of the relationship.

The first key part is observation and a sort of allowing others to be who they are. Drucker writes, is to "accept the fact that other people are as much individuals as you yourself are." They have strengths, preferred ways of getting things done, and values that matter to them. "Each person works his or her way, not your way."

There are a lot of dim bosses out there that don't get this. If you understand this, though, and are willing to try to work to others' styles, you will flex and stretch and grow, and you will not be one of those bosses. You will be the employee that everyone wants on his team, you will be the manager that everyone wants to work for.

You can start as an employee by observing your manager and her way of working, identifying her strengths and concerns, and seeing when she is most effective. This can be a matter of career life or death. As you get better at this approach, you will be able to more easily apply it to coworkers and reports, whom you often know better than you know your boss.

The other key part of responsibility for relationships is communication. Drucker writes that as a consultant among his client companies, the single most common source of friction he encounters is failure of communication. The most commonly under-communicated information is what different people are working on. We may sit next to someone who works on an entirely different project with wildly different needs and even different working hours.

It is vital that we spend part of our time each week making sure that key stakeholders are aware of our work. Key stakeholders include bosses, those interested in particular projects, and those helping us work on those projects. It's important to keep even direct reports informed so that they can take ownership and bring their skills and knowledge to bear on questions that may arise.

The Second Half of Your Life

Drucker's book concludes with a section entitled The Second Half of Your Life essentially about what to do during retirement and by extension what kinds of things non-retired people might do in our free time. He draws attention to three common approaches:

Second career. Often, pivoting accomplishes this. If you are the VP of Sales at a tech shop, try pivoting to VP of Sales at an agricultural supplier. The key thing about a pivot is that you keep one dimension of your work (or life) anchored while changing up another dimension.
Parallel career. This often means taking on a part-time job or starting a cottage industry as a "side gig". Experienced executives might join the board of a women's crisis shelter, Drucker offers, or a young advertising specialist might learn to code and combine skill sets.
Social entrepreneurship. Social entrepeneurs focus on how to add value to society using the skills, experience, and connections they've developed. If you can afford to live on and even reinvest your investments, this approach might take the form of starting a nonprofit. If you're still mid-career, I would offer that you might do volunteer work or help an existing non-profit to develop new avenues for helping folks in need. For instance, you might offer career-counseling services to a homeless shelter.

Conclusion

Drucker's book Managing Oneself feels somewhat dated here and there, especially in his cultural references. Don't let that stop you from a careful reading, though. My experience is that the book is very prescient and probably applies now even more than when he first wrote it. The key takeaway for me is that you can learn to manage yourself, and that by doing so, you will need to be managed by others less, and will be better at managing them as well.

What I've Been Learning Piecemeal

Ryan Haber — Mon, 20 Jan 2020 05:00:00 +0000

tl;dr: I’ve been lengthening the legs of my skills “tripod” - and done piecemeal, it’s been fun and easy.

A great mentor of mine, Olivier Meyer, told me one time that in his mind, product management is like a stool resting on a trio of legs:

organization skills and knowledge - things like running a meeting well, planning and revising plans
business and human skills and knowledge - things like communicating the correct information clearly to the appropriate audience
technical skills and knowledge - the subject matter of your product

I think he was right. Furthermore, I think these three legs apply to all professionals, albeit in proportions that vary with your roles and goals.

Most of the time, when we start a new role, we have a base set of skills and experience around it, but want - need - to keep growing those skills. That was certain the case for me. I came into product management gradually from technical writing and API documentation. I’m naturally a people person, concerned with others’ opinions and feelings, and I take real pains to express myself clearly and help others express themselves clearly when they seem to be struggling with it. As I’ve gotten older, and with good mentorship, I think I’ve gotten more discreet. That is, I’ve gotten better at knowing what to say and to whom… or what not to say. Great. So I have a base set of people skills, management skills, and tech skills.

Then what?

Well, a while ago, I set upon a program of actively growing my skills. My temperament is decidedly not bent toward taking classes and earning degrees. So instead, I’ve been doing things piecemeal - as I want, when I want, based on my interests and needs. In the last few years, here’s how I’ve been turning myself toward upping my three product management legs.

Organizational Skills and Knowledge

Lots of books and seeking lots of mentorship. Most recently, my manager, Leonor Alfonso, has been amazing at patiently helping my grow in this area.

But other times, I have particular questions or find myself shouting in my head, and need a way of resolving these without going to someone else. Lately, for instance, I needed to produce a roadmap for further into the future than I felt I could really predict. “What do I do!?!”

Getting Things Done: The Art of Stress-Free Productivity by David Allen is a great manual for keeping tasks organized and moving along without stressing over it all.

Brett Harned’s overview work Project Management for Humans: Helping People Get Things Done is great for helping you get your bearings when your job is running complicated or multi-person projects.

Todd Lombardo’s Product Roadmaps Relaunched: How to Set Direction while Embracing Uncertainty is a must-read for making roadmaps not lie and generally suck.

Business and Human Skills and Knowledge

Books and mentors: this is a theme for me with learning soft skills. The number one thing for learning soft skills is not being ashamed of not knowing having them.

I’ve sought mentors to my great benefit. Bosses can be great mentors. They are human, so we can’t expect them to know everything, but I have found that finding out what they know and learning from them is very fruitful. The aforementioned Olivier Meyer and Scott Hurrey have both been very helpful for me in this regard.

Crucial Conversations: Tools for Talking When Stakes Are High, Second Edition, by Patterson, Grenny, McMillan, and Switzler, is a fantastic book. It’s not about how to win conversations, but about how to have them when they’re hard. It’s especially good for helping me not only keep my cool but for helping me help my conversation partners keep cool.

Never Split the Difference: Negotiating As If Your Life Depended On It, Chris Voss and Tahl Raz, is amazing. Life-altering. It saved me 50% on the cost of roof repairs in my first week and has gone on to help me manage upward, manage downward, and build consensus with clients and coworkers alike.

Technical Skills and Knowledge

My product management work isn’t especially technical. I work on a product that deals with non-technical subject matter and faces end-users who aren’t technical people. It’s also been more than a few years since I was a computer science minor. While the theories I learned have never left me, the core skills involved in programming have definitely progressed. And while my goal is not to be an engineer, well, the more you know, right?

Dev forums : We all know about stackoverflow. But the last few years, I’ve done a lot of lurking on dev.to. It’s a great site.

Code challenges : Lately, I’ve started doing some of dev.to’s coding challenges, like make a function to convert rgb to hex. Here are my results of that one. Nothing complicated, but fun. And in this one, I learned that python has string interpolation very much like my good old friend C.

Teaching others : My HTML and CSS skills are sharp and my Javascript skill level is adequate for my needs. I find myself helping people who want to tweak their blogs or build personal websites or portfolios without using a code-free builder. But my favorite protegee is my niece. She’s 12 and learning to code. After mastering scratch a visual coding platform for kids, she wanted to cut her teeth into something more significant. So I’m working through a book (Creative Coding in Python: 30+ Programming Projects in Art, Games, and More) with her. She’s loving it and so am I. While I know what a variable is, I have found myself learning little bits here and there, filling in gaps in my piecemeal learning. If you’re an engineer and your protegee is a college student, this book is not right for you. But mentoring and teaching are right for everyone.

The Takeaway

The takeaway here is simple. Whether you’re a product manager, a UX designer, a tech writer, a dev, or even a recruiter - you’re going to benefit from building organization skills, human skills, and technical skills. A recruiter doesn’t have to be a dev or know all the dev skills, but it’s good for recruiters to learn the distinction between Java and Javascript; a dev doesn’t necessarily have to manage a fleet of people, but it will only help her career to know how to keep a large project organized. And the good news is that you can learn these things piecemeal.

Photo by Simon Abrams on Unsplash

How to Docs and Why

Ryan Haber — Mon, 10 Jun 2019 04:00:00 +0000

tl;dr: Nothing is worse than having to write docs - except not having them when you need them. You want not too little, but not too much.

Why Bother?

Docs-writing sucks. That’s why you don’t want to do it, right? Well, that’s fair enough. And even in a world where we rightly prefer working code over documenting the everloving f*@k out of things, there are some good reasons to document your work - whether as code or as an end-product.

You are helping yourself.

The better your documentation is, the fewer questions people will ask you in the future. And when they ask you questions, you will be able to send them a link instead of writing documentation. Based on this reasoning, it is a good idea not to document things that nobody will ever care about. You might be surprised that somebody asks about X. If that happens, answer their question and add your answer to the documentation in a place where people can find it. Also, you might have to revisit something six months or a year later. It will help you if you made good docs while you were working on it the first time.

You are helping your future self.

You will one day arrive at a new job or join a new team. You will hope that the people there have written good docs to help you get started. Pay it forward by writing good docs for whoever comes after you.

You are helping your team.

You might win the lottery one day and leave suddenly. Your team will love you if it make it easy for them by documenting your work well.

You are helping our clients or customers.

When our stuff is easy to use, people use it more. If it is not easy to use, we can at least explain it and make it feel easy. When we do these things, we get more sales and more renewals.

What Makes Good Documentation?

Quantifying the Value and Quality of Documentation

People often think that the value of docs is subjective or unquantifiable. This is rarely the case.

The value of writing is that it can be written once and shared many times, whereas in-person or real-time forms of communication need to be repeated each time a new person needs the information.

Time is money. Wasted time is wasted money and lost productivity.

If I answer a question for the external developer community and it takes me 10 minutes, and at my pay scale that is, to keep things easy, say $10, then the company pays $10 each time I answer that question. If the question comes in daily, then in the course of a working year of 240 days, the question costs the company $2400. If I write a good doc and make it easily findable at a cost of $60 one-time, I think you can see how the savings is dramatic. In my experience, a well-written, easily-findable answer eliminates the question 90% of the time. For the other 10%, you can smugly send a link and sit back while the past-you does the present-you’s job for you. This scenario is simplified, but it is a real-life scenario that I live repeatedly. We all answer any number of questions over and over again because of disorganized knowledge management. This problem is not unique to our company.

Depending on the complexity of your documentation problem and your channels for interacting with your docs’ users, you can gather just this sort of data and more. How long does it take to read a doc? How many times do people read the doc and then contact customer support? How often is a question asked of customer support? How easy is it to find the document in the docs repository when you know it exists? How often do internal or external search queries for relevant questions bring up the relevant doc or an irrelevant doc? What is the user behavior like when they land on a doc from a seemingly relevant search query. All of this questions can be answered objectively using modern technology. These answers, in turn, are the first data points for understanding the cost of difficult or missing documentation. They are a good first step in figuring out what needs to be documented or what docs need improvement.

The question is, then, what things should be documented?

Document questions that are clearly or probably going to be asked.
When you get asked a new question, might as well write it in a generally-applicable way if possible and quickly insert it into the best location in your documentation structure.

What should not be documented?

Things nobody cares about
Things that you are proud of but really only you care about, like how hard you worked - tell your mom or write a blog post.

The trick is to anticipate the probable audiences for a subject matter and what they probably need to know.

So much for the value of a doc.

What about the quality of a doc? Isn’t this subjective?

No. Not at all. A doc has a job to do and it is good inasmuch as it accomplishes that task. That is the absolute and completely objective standard to the quality of technical documentation. Suppose I write a document for experienced Java engineers and, out of a 100 engineers, 17 understand it. No matter how smart I think I am, I have failed. That score will save very few people any time.

There are other objective standards, too. The subject of readability, the ease and speed with which prose can be read and understood, is a very well researched topic. See https://readable.io or https://hemingwayapp.com for free or low-cost readability scorers that will tell you the difficulty or ease of reading your doc and what makes it easier or harder. They typically use a set of established formulas to return a grade level, a letter grade, or a percentage score. They often give good tips for improving your particular text. Aim for a 7-9th grade reading level. This isn’t dumbing anything down - this is making it so your document’s user does not have to figure out what you were trying to say. This is just making yourself plain to even a teenager.

The principles and tips below will help you take your “business-ese” and easily transform it into clear text that your intended audience can understand. One caveat is that big words affect readability. Some words, like utilize should almost always be replaced with use because they mean the same thing and use is easier. Other times, you just have to use a bigger word like reciprocation. That’s OK. Just be readable.

Understand Your Audience

Good documentation is written for a specific audience. The author understands the audience and writes only those things that the audience needs to know. The author explains those things in a way that the audience can understand. Some examples include:

Other engineers / your future self
Educated, intelligent non-engineers: PMs, Designers, etc.
Managers, Directors, or Executives
External developers
Marketing or sales team members
External end-users

Understand Your Audience’s Needs

Audiences need different things at different times.

Conceptual : Theoretical overview that explains the What? and Why?
Tutorial : How-to steps that explain How to accomplish a task.
Reference : Look-up material when your audience needs to know a fact, like a definition of a word or the parameters accepted by a method.

Make a Matrix of Needs

Once you have made a grid of audiences and their potential needs, you can make rational decisions about which ones to document. For example, consider the subject of something technical like a data pipeline. In the follow matrix of needs, we mark spaces with X if we think we probably do not need to write the document because the audience does not likely need it. Otherwise, we comment on what the document should accomplish.

Audience	Conceptual	Tutorial	Reference
Other engineers	Explain to other engineers what the pipeline does, how it works, and why we set it up that way, so they can get started working on the pipeline. Engineers looking at your code need to know: (a) what you did and (b) why you did it that way. (A) should be clear from the code itself. Comments can help explain (B).	Help engineers set up their environment.	List of classes and methods.
PMs / POs	Explain to PMs / POs in a simple way what the pipeline does, how it works, and why we set it up that way.	X	List of unusual words and their meanings in the context.
Executive summary	Explain in simple, common words, very briefly, what the pipeline does and why.	X	X

Universal Principles

Concise

Do not use more words than you have to. If a sentence can have 10 words and you write 13 words, you have written 30% more than you need to. You ask your reader to read 30% more than they need to. Your writing feels fluffier the more you do this. If you do it a lot, it becomes harder to find answers.

Pro tip: Avoid using adjectives. Adjectives are usually unnecessary and often change. If you write, “The blue button,” a UX designer will come along and change the color and your docs will be wrong.

Example:

I went up to the store in order to buy some organic eggs. = 13 words

I went up to the store ~~in order~~ to buy ~~some organic~~ eggs. → Remove words that do not add value for the particular audience.

I went to the store to buy eggs. = 8 words = 38% savings. → Multiply this savings across 100 pages of documentation. &

Complete

Try to include everything that somebody is likely to want to know. Do not include things that will not help other people with their work. If you are really proud of something, show it to your mother. The rest of us will be proud of you when we can read your docs and appreciate your work without have to read all the stuff you are proud of.

Pro tip : Do not create the same content twice if you can avoid it. Instead, use links and iframes to connect or display content as needed. Put related pieces of content close to each other. If related content cannot go nearby, connect them using links, iframes, or another such tool.

Clear

Clarity is objective. If your intended audience does not understand your docs, your docs are not clear.

Pro tips : use a readability checker like https://www.readable.io or https://www.hemingwayapp.com to help you achieve the right level for your writing. For technical documentation, aim for levels 7-9. If the only “problem” with your writing is that you have a number of large words that are necessary in the context, that’s OK. You might have to use words like application or analytical that typically make a doc a bit harder. You do not have to use words like utilize when a word like use is just as good.

Correct

Get someone else who understands your content to sanity check it for correctness. If your document is found by a reader to be inaccurate, they will wonder why they should read your work anymore. In some situations, inaccurate information can cause serious harm.

Organize Your Content

General principles:

Keep related content close to each other. If a user only needs a bit of information in one place, then put that information in that place. If the user needs the information in more than one place, put it in one place and then link, iframe, or mention it in the other places. Example : To log into your account you need credentials. For steps to get credentials, see Getting Credentials.
Avoid writing the same documentation twice. When someone updates one place, they will often forget to update the other. The two pieces of content fall out of sync and the documentation as a whole becomes less trustworthy.
Make different kinds of content (conceptual, reference, etc) visually distinct. Separate them from each other when it makes sense.
Use clear heading titles. Headings should answer a question. Headings for conceptual and reference content are usually nouns. Headings for tutorial (how-to) content should start with a verb. Generally, headers should not rely on knowledge that a person will not have before reading the content. Bad : How Do I LMGTFY? Good : Using Let Me Google That For You Better : Making Your Friends Feel Bad by Pointing Out How to Google
Bullet points vs numbered lists:
- If order does not matter, for instance, when you describe best practices that are independent of each other or when you are sharing concrete facts, then use bullet points (unordered list).
- If order does matter, for instance, when you list the steps of a procedure, use a numbered list (ordered list).
Use a table of contents for a long document or for a collection of documents.
Each thing should be about one thing. You should be able to summarize every book, chapter, paragraph, and procedure in a single sentence.
Use tags. Try to use existing tags instead of inventing new ones, whenever possible.

Simple Tips That Anyone Can Do

Write simple text. Short sentences, easy words, active-voice verbs all help readers quickly move through text.
Put the documentation where it is relevant. If it is relevant to multiple things, make it a separate topic and link to it from all the places where it is relevant.
Use existing standards whenever they apply.
Use formatting consistently. Otherwise, the formatting loses meaning. Below are some common standards for documentation formatting.

Common Standards for Formatting Technical Documentation

Boldface - use boldface to highlight exact words as they appear in the UI when a user needs them for taking action. If they are not exact words or they are not needed for action at that moment, don’t use boldface.

Monospace - use monospace to indicate words or string as an exact match in code or other technical sources like config files.

Italic - use italic to indicate that words or string is an exact match that is not in code.

Ordered lists - use for steps or other information in which the order is essential

Unordered lists - use for information in which the order doesn’t matter

H1 - top-level subjects, unless there is no special format for a title, in which case, use H1 for the title of a document

Photo by NeONBRAND on Unsplash

Soft Skills You Need

Ryan Haber — Sat, 18 May 2019 04:00:00 +0000

tl;dr: There are great resources out there to help you learn to manage yourself and others, negotiate, network, and more. Use them.

Why Soft Skills

There’s a lot of talk about soft skills lately. It may be that we’ve emphasized understanding STEM subjects to the detriment of working with human subjects. If you google most important soft skills, you come up with a lot of different lists. In my own life the following skills have made a measurable impact. Measurable, because as I have learned them, I have seen my career advance not only in responsibilities but also in dollars and cents.

The reverse is true. In my past I have made some “career limiting moves”. Now that I know better for the most part, I cringe when I see others do these things because they lack soft skills. Six months after telling the boss in public that his idea is dumb, the social cludge wonders why the boss didn’t put him up for a promotion.

Humans are humans. Learning to work and play with humans is pretty important.

With each skill, I make a recommendation or two for reading or viewing. Of course, the best way to really improve is to talk out scenarios with mentors and smart peers.

The Skills

Managing oneself, one’s subordinates, and one’s superiors

Managing Oneself This book is a classic and I can see why. It’s short and sweet and helped me to understand my study/work habits and needs, and to quickly understand those of the people around me. This understanding in turn has helped me to figure out how I can both be of service to them and also keep them from getting in my way 🙃.

Negotation

Never Split the Difference This book has been nothing short of lifechanging for me. I needed repairs to my roof. The roofer gave me his estimate. And with one question, which I learned to formulate by reading this book, I got him to cut his price down from $900 to $450.

Networking and Crossing Silos

How to Win Friends and Influence People is a fairly wordy one, but is good nonetheless.

Never Eat Alone is well received, but I haven’t read it yet. If you read it, let me know how you like it below 👇.

Having hard conversations

Crucial Conversations does not teach you how to win conversations, but rather how to have them when the subject matter is emotionally charged. It has really helped me learn to keep calm and help the others in the conversation also keep an even keel and hear each other out.

Problem solving

The Art of Strategy: A Game Theorist’s Guide to Success in Business and Life is a fantastic book. It doesn’t just outline strategies. Rather, it goes over, chapter by chapter, key principles and techniques that you can use to put together a strategy fitted to your situation, be it a board game or a career move.

Time Management

Getting Things Done: The Art of Stress-Free Productivity was a real game changer for me. Since reading it, I’ve been able to engage in more projects and activities and feel less stressed than ever before. I don’t use his system fully, because make no mistake, it is a big, hulking system, but I use some of its core principles and I am very glad that I do.

Written Communication

The Complete Plain Words is a classic of clear and productive writing. It is easy and has lots of examples. You probably won’t read it all in one sitting. Instead, read it in bites and let it sink in.

Oral Communication

How to Speak, How to Listen is a classic. I haven’t read it though, so let me know if you like it. :D

On Speaking Well by a former presidential speechwriter. I haven’t read the book yet, but this woman knows her stuff. I suspect a lot of the public speaking skills translate, with some tweaking, to small-group or one-on-one conversation.

I also highly recommend the YouTube series Charisma On Command.

One Stop Shop

Soft Skills: The software developer’s life manual is a good book. I haven’t read it all, but the parts that I read were really good. It covers a lot of the topics above and will be helpful not only for software developers, but for people who sometimes feel awkward. Or who don’t, but maybe should 😊.

Photo by Rob Curran on Unsplash.

Anatomy of a Good Ticket

Ryan Haber — Mon, 01 Apr 2019 04:00:00 +0000

tl;dr: A good ticket is clear, correct, complete, and concise. It uses straightforward grammar, includes background information to aid good decision-making, and sets clear expectations. A good ticket is neither too big nor too small.

The Problem

Unless you are a single developer writing code to solve your own, individual problem, the people who want the software are not the exact same set as those who make it. As a result, communication is necessary between the set of wanters and the set of makers. And the greater the size of the sets and the less they overlap, the more crucial it is to have clear written communication to avoid wasted effort.

The Solution

Work requirements usually get broken down into tickets. These tickets can be seen as atomic or, perhaps, as being small molecules.

Good tickets include background information. This aids good decision-making by people who come after the original writer. It is often packaged as a user story. A user story explains:

who will benefit or has a problem that needs to be solved
the problem or the desired solution
the end goal of the beneficiary

The format of a user story is usually something like:

As a (kind of user), I want/need (solution to problem) so that I (experience or result obtained).

With this information, the product development team of designers and engineers can start solving a problem, enabling them to take ownership of the problem and the customer’s pain. Most importantly, it’s formatted in a way that engages their skills and talents, which is why they were hired in the first place.

The Four Cs of Good tickets are:

correct - They reflect what is actually wanted, precisely and accurately. The key to this is that the Product Manager (PM) or Product Owner (PO) must work with stakeholders and understand industry standards. In case of uncertainty, a good PM/PO works with a very knowledgeable subset of the product team to arrive at a precise and accurate definition.
clear - They are clear. I recommend running the description portion of tickets through a readability scanner like Hemingway App.
complete yet concise - They contain everything the team needs to get started, otherwise they will have to waste time coming back for more information. While writing a ticket, you should cut unnecessary details, attachments, and even words or phrases; otherwise, the ticket quickly becomes a jungle, and key information will get lost in the clutter.

If a ticket lacks any of these four Cs, the team will waste time having to reconnect and sort through old notes trying to figure out what was meant and whether it still applies.

Good tickets use straightforward grammar. This is part of clarity. It is also worth calling out specially. The point of writing a ticket is to make its contents understood. Lots of people unconsciously use unnecessarily long or complicated words and phrases. A common offense is to use words like utilize rather than use. The cumulative effect of big words and long sentences is cluttered communication. Avoid jargon that your intended audience is unlikely to know. Every extra or unknown word increases the chance of a reader getting distracted or giving up.

Run your writing through a readability scanner to see where you can make improvements. Aim for writing at the 7th to 9th grade level so that any adult can read it quickly and comfortably. My favorite scanners:

A good ticket is not too big or not too small It suits the time-frame and team members involved in its execution. Think of an atom or a small molecule, not a rocket ship.

A Bad Ticket

Imagine a ticket’s contents broken up into this form.

form field	field contents
summary	Fix developer portal
reporter	Ryan
date created	2019-03-29
team	Front End Team
current assignee	tbd
status	backlog
user story
acceptance criteria	1. The fly-out panel on the left should work. Right now when I click it, nothing happens. When it opens, it obstructs my ability to interact with other controls on the page and this interferes with my workflow preferences. Then I can’t get it to close by clicking the X button.
Definition of Done	No bugs
attachments
work log
last modified by
last modified date

There are a few general problems with this ticket:

The summary is vague.
The reporter field may not give enough information to help readers contact the writer.
Without background information, the Front End Team won’t really know why they’re doing what they’re asked to do.

The acceptance criteria:

is vague and incomplete. It does not provide clear guidance about what is expected or required.
jumbles multiple problems into one ticket.

The definition of done states only the obvious.

A Good Ticket

Let’s look at the same ticket reworked.

form field	field contents
summary	Developer portal’s left flyout panel blocks underlying form
reporter	ryan.haber@mycompany.com
date created	2019-03-29
team	Front End
current assignee	tbd
status	backlog
user story	As an external developer, I need to enter long key values in a form on MyCompany’s developer portal that I retrieve from a flyout panel in the same portal, but this panel covers the controls. So that I can work more accurately, I need to easily enter these values without having to jot them down on paper.
acceptance criteria	1. The panel helps developer-users capture and enter the values in some digital way. E.g.: “copy to clipboard” button or at least a copy-and-paste-able field to hold any values that might need to be recorded by the developer.
	2. The interface makes valid workflow(s) intuitive.
	3. Success is indicated by a 50%+ increase in the rate of form completion over 3 months.
Definition of Done	1. Finished build asses all unit and integration.
	2. Finished build accommodates at least 25 concurrent users.
	3. Meets all standards set in MyCompany Base SLA.
attachments	userFeedbackSurveySummary.xlsx
work log
last modified by
last modified date

What do we see in this revised ticket?

The summary is clear and complete.
Readers will know who to contact with further questions.
The user story provides background information that the development team needs to think of a good way to solve the problem.
The ticket does not not attempt to micromanage the team, but does provide clear requirements.
The ticket has peeled off separate, albeit related, issues for other tickets.
Other useful information is attached that may help the team get a sense of what is frustrating users.

If you use this approach, you give the development team the information and freedom they need to make intelligent decisions to solve a problem rather than to act like cogs in a machine that needs constant managerial tinkering.

Conclusion: Coordinate - Not Dominate

You wouldn’t want an urban planner telling a civil engineer how to build a new bridge. The urban planner understands what is required, coordinates other moving parts, and makes this information available to the architects and engineers who then develop and implement a safe, economic, and beautiful design to enhance a city and serve its needs.

Likewise, it is not the role of a product manager, product owner, or business analyst to tell engineers how to do their job. Instead, these product management types should make clear what outcomes the stakeholders need and what constraints the business and its market impose on the situation.

The atomic unit of organization for the workflow that results is a ticket or issue. A good ticket serves as a point of reference for all involved. When they are well written, managers can arrange them into different to-do lists, epics, user story maps, or any other pattern they like. Managers can assess relative or even actual costs and values for development and then make sound decisions about organization priorities.

That all starts with a good, clean ticket.