How much assumed knowledge is enough?

I spent years as a developer advocate targeting beginners to particular technology, topics, or products.

I'm very specific about this because my definition of beginners did not include folks who were new to coding, but might be new to working in cloud or SaaS. They didn't have to be full time developers, but they did need to know some amount of programming. I would stop to explain some fundamentals, but really I assumed folks would get most of their fundamental knowledge from somewhere else, whether it was a degree, bootcamp, certification, or someone else's content.

I don't want to assume so much knowledge that I alienate users, but, at the end of the day, I need to assume some knowledge.

I often thought (and still think) about the minimum amount of knowledge required to get through a how-to or complete a task. For example, if something required an async call or needed to happen across multiple threads I would acknowledge the why, maybe touch on the how, and if I was feeling particularly generous (and knowledgable) I would mention the pros and cons of shoving this code into production as-is.

If you've heard me speak or attended a workshop I've lead I always warn folks to not take snippets or example code I've written and put it into production. It's often untested for scale, security, or, more literally, just does not have testing! All things you need to consider carefully when "productionalizing" code. Don't just take it and run with it.

This isn't a scathing blog about how devs of this generation just C&P their way across Stack Overflow - that's a tired opinion. This is a fair warning to myself and other technical content generators that your example code will likely end up in production, no matter how many alerts, notes, comments, and admonitions you make.

So how do we acknowledge this while offering an easy to maintain, digestible experience? How do you build examples and content meant to help educate developers without huge maintenance costs or any other gotchas on either side?

Facilitate rapid prototyping

This one is huge, so it's first because I'm long winded and you'll likely stop reading soon anyway.

We live in an agile world filled with near-instant gratification. Your project manager or stakeholders demand significant, regular progress which starts at the very beginning of the software lifecycle, sometimes even before.

How many times have you find ourself saying "oh I just hacked this together" or "I PoC'ed this and it looks like it will work for us" only to then find yourself in a position where you need to deliver and you need to deliver this week or this sprint. Have you ever started from scratch? Or do you typically build off of what you had?

I'll be honest, as a developer, I've never thrown out PoC (proof-of-concept) or "hacked" work. In fact, I'd go so far as to say I've never been empowered or support to do that. This isn't a jab at my previous teams or managers, but given the choice between starting from 0% and starting from somewhere between 30-65% I'm simply too lazy to throw away work.

Any example snippet or sandbox may be pitched as something great for prototyping, but rarely do I see situations where prototypes are chucked in the bin and not evolved into production (hopefully worthy!) apps.

Target an MVP

My goal in Developer Experience is to get you through an enjoyable, efficient experience with our products and tools so you get to focus on delivering a solution for your use case.

This means I'm looking to cut and trim everywhere I can while still providing you a meaningful experience. This is no different than going through an MVP (minimum viable product) exercise. What's the bare minimum you need to be successfully onboarded?

Acknowledge you will not be able to cover every features and every corner of your product, but don't reinvent the wheel either. Give devs building blocks so that each step of the way through your how-to or documentation they can build on their foundational knowledge but don't be afraid to keep it lean.

Save devs from themselves (if possible)

To give you a concrete example, we evaluated our community through surveys, polls, and forum questions and realized their Java knowledge was beginner at best and their grasp of concepts like multi-threading, synchronous and asynchronous processing, and other complex topics just wasn't there. There is a difference between writing code that's functional and writing code to be performant. There is room in tech for both.

We discussed modifying some of our getting started content to remove lines that may lead to issues down the road because of this conclusion. For example, blocking and non-blocking code was not explicitly obvious.

send().join()

Did you know that's a blocking call to wait for the issues command to be executed on the workflow engine?

So we modified it to this

send().whenComplete((result, exception) -> {})

to register a callback to be executed if the command on the workflow engine was executed or an exception was thrown.

Now while both are perfectly acceptable for an example, sandbox environment, of even a PoC, the first example is not going to scale in the way we know process automation projects will in a production or production-like scenario.

While some devs will be able to recognize this, we want to lower the barrier for ALL devs, so we adjust without having to deep dive into the fundamentals of parallelism. We've able to introduce the topic, how it works with our product, and point them in the direction of more information or give them terms they can search around and educate themselves on. And most importantly, we've set up the dev on a good path that if this code ends up in production and scaling, it's not as fragile.

I think it's also important to recognize you can just have a bad, unfocused day as a very experience Java dev and miss this detail. It may not hurt you at 1-10 processes

Special thanks to @berndruecker for the fixes in this example!

So where do you draw the line at enough assumed knowledge?

My favorite answer - it depends.

I like to lean heavily on user data and personas. It's unrealistic to think I can teach everyone programming fundamentals, how to use our products, and be good at all of that.

I keep the three things in mind - how can I facilitate rapid prototyping, introduce them to the MVP, and save devs from themselves when using our products so they can get what they need from the experts in that space or topic.

How do you handle this? Or maybe, what do you expect in your documentation experience? Leave me a comment and share your thoughts.

Cover Photo by Eli Francis on Unsplash