Blog

3 Things I Learned from My First Week as a Developer Advocate

This week I started my new job at JetBrains as a Java Developer Advocate which I am super excited about! It’s been a fantastic week and my feet haven’t really touched the floor, but I wanted to summarise my learnings from week one. I hope you find them useful!

Free-Photos from Pixabay

“>

Asking questions is a Good Thing™️

I’m not normally one to hold back on questions, but I find that it’s really easy to be less forthcoming with queries when you join a new company and start doing a job that you’re new to as well. After all, no one wants to look, or feel, stupid.

Of course what I need to remember is that I can’t possibly know everything. This feeling is amplified many times over when you are new to a company, a team, and a role. I had already obliterated this piece of advice by day #4 so I urge you not to do the same. Fortunately I was reminded of this by a colleague who clearly thought I needed to hear it (they were totally right, I did — thank you!).

Everytime I struggle to ask questions in unfamiliar environments, I remind myself that:

  • If I don’t know the answer, there’s a very good chance that someone else doesn’t either

  • Everyone wants me to succeed, I need to ask the questions that will empower me to do just that

  • Questioning shows engagement. It shows that I care and it helps me learn

Struggling improves learning

This may sound like it flies in the face of asking questions, but there has been some times this week when my immediate team were otherwise engaged and couldn’t answer my gazillionth question. As anyone who knows me will attest to, I am extremely stubborn when it comes to certain things. As it turns out, bending IntelliJ to my will is one of those.

And I got there, I solved the problems, each and every one of them by myself with the aid of Google and at times a walk around the block to work out what I was missing. It feels insanely good to solve a problem by myself and I will never (like ever) forget the following:

  • ⌘⇧8 gives you column select mode (I typed it that many times that it’s now in long-term-can-never-forget memory)

  • If you want IntelliJ to show intention actions and quick-fixes (⌥⏎) you need to make sure the caret is on the word you want it to deal with, not just the line. IntelliJ will highlight the word which is very helpful

  • If your Project window isn’t colour coded and you can’t interact with it, it’s entirely possible that you’re looking at the git Repositories window instead of Project… oops

  • I don’t need a 3rd party app for git, I can use ⌘9 and see it all in IntelliJ, perfect

I have a lot to do

It’s a really steep learning curve, I knew it would be and I am 100% okay with it. However, that doesn’t detract from the fact it’s hard, likely really hard. I did catch myself feeling quite overwhelmed quite quickly (day #3), but again, I was reminded that I can’t do everything, and neither can anyone else.

The skill is triaging the immense workload and being smart about what I work on and how I work on it. Some of the things I’ve found helped me are:

  • Automate it. If I can automate any part of my workflow, I do. I’m confident that there’s plenty more I can do in this area and I plan to sieve through the huge wealth of knowledge that my team and the business has to give me some more go-faster skills

  • Talk about it. Talking with my team has been invaluable. We prioritise work together, we challenge each other’s viewpoints, we bring new information to the table and we help each other.

  • Share it (early and often). As I’m working on new things I’m sharing them throughout the process. It’s much better to make a small change to process or content early on then wait until a big bang at the end!

Summary

When you’re in unfamiliar territory and you’re grappling with all sorts of unknowns and knowledge gaps, my top 3 tips are:

  • Ask lots of questions, they’re a Good Thing™️! ❓

  • Don’t worry about struggling to learn something, when you do crack it, and you will, it will be embedded in your memory for good. 🙌

  • Look at what you’re doing and share your workload with those that can help and empower you. 🥑

Remote Behaviours

Before the UK was overtaken by Covid-19, I wrote an article called Stop Calling them Soft Skills. It’s something I’ve always been passionate about and it once again came to the forefront of my mind this weekend when it dawned on me the immense pressure that we’re all in right now as we adjust to life under lockdown.

First up, wherever you’re at right now, you are awesome. You should know that. Irrespective of whether you’re working from home with kids on your lap watching Frozen II on loop, putting in long, emotional hours in our hospitals, delivering meals for the elderly and vulnerable, or indeed working in any of the front-line positions, there are so many. You’re saving lives and I am incredibly grateful to you all.



Many of us are now working remotely and that brings its own challenges. It occurred to me that the behaviours I associate with the phrase soft skills might be even more crucial when we’re working remotely.

Genuinely I wish my makeshift desk looked this good!

Image by Free-Photos from Pixabay

The original definition of these behaviours was:

…a combination of people skills, social skills, communication skills, character or personality traits, attitudes, career attributes, social intelligence and emotional intelligence quotients, among others, that enable people to navigate their environment, work well with others, perform well, and achieve their goals with complementing hard skills.

So how does working remotely impact these behaviours? And how can we help people working remotely to navigate in their environment, work well with others, perform well and achieve their goals?

Remote Working and Behaviours

It would be very easy to list the things we might find hard when interacting with our colleagues remotely, especially for those of us that are not accustomed to it. It could be summarised as:

  • Harder to read people’s body language and social interactions

  • Harder to manage the flow of communication between multiple people

But this is bigger than that, we have to factor in that for all us existing and new remote workers, we are all under an immense cognitive load in addition to the obvious challenges. Many of us:

  • Have kids at home (and school is most definitely out for summer)

  • Have never done this before

  • Have vulnerable people in their house that now need additional support

  • Have vulnerable people they can’t see, but worry about

  • Are vulnerable themselves

So what can we do?

We don’t need to modify our behaviours, not really. We don’t need to get hung up on the challenges of remote communication, that’s a given.

We just have to amplify our behaviours. We have to shout them (metaphorically perhaps) from our rooftops/balconies (Europe I’m looking at you ❤) or our windows for those of us in the UK.

Most importantly we need to act those amplified behaviours out in front of our laptops.

My top behaviours to amplify are:

  • Be empathetic

  • Act with kindness

  • Show compassion

  • Respect everyone (and their families)

  • Have patience

Looking after yourself

  • Make time for yourself. I appreciate this is much easier said than done, but if it’s at all possible, take whatever time you can for you 📚

  • Ask for help; don’t suffer alone. We’re all in this together and if you need help then so does someone else 💛

  • Be you. Be real. I ditched the make-up on day #3. 😏

  • Respect your time. Just because your laptop is on the dining room table does not mean you need to look at it on a Saturday night. Don’t burn out 🕯

  • Be honest with the people around you. Whether they are your family, friends, or brand new housemates. Ask for support from those physically located with you or those you can phone ☎️

Looking after others

  • Video-call your colleagues without a work agenda and ask how they are, listen to them 🎥

  • If you have the capacity to do something to help someone else and improve their day, do it 💗

  • Give a wave to the little kid sitting on the parent’s lap on your video call, it will make their day. Respect their family, they’re not enjoying this either 👶🏻

  • Make allowances for everyone. We’re all finding our way and we’ll all make mistakes on the way as we change and grow 🌱

  • Forgive your colleagues when they drop more balls than usual. We’re not all as good as juggling as we might think right now️ 🎾

And in case you forgot this already, you are awesome!

Tips for Writing App Release Notes

The iOS, and I assume Android, platform provides us with a few precious characters for each release. There’s no guarantee a user will read them, but, if they do, you had better make sure that you’ve treated that space with the utmost of love and attention and filled it with amazing words for your users!



Will anyone read them?

Like this page, maybe, maybe not, but the better question is:

How will I show the user that I genuinely care about their experiences and goals when using my app?

So what do I write?

This is a good time to think about what action you want to invite the user to take in this revision of the app. Think about their experience. What action are you enabling them to do? How does the new functionality further your users’ goals?

Can I use humour?

It often depends on your voice and tone guide (if you have one), but irrespective of that, there are still some guidelines you can use.

  • Don’t belittle the user, ever

  • Don’t downplay a bug fix with humour, especially one that has caused a lot of challenges

  • Be careful of localisation, humour rarely translates well

  • What sounds funny in your head might not be funny on paper

  • Stay away from stereotypes, they never end well

How much detail should I go into?

I think some writers struggle with this because we all love words. However, by prioritising and layering the information you can give your app shiny release notes that your users will get value from (which will give you a warm fuzzy feeling too).

You get a couple of lines to tell your user why they should click more, make it count!

The Important Stuff

  • This is the bit of text the user can see without scrolling irrespective of the responsive display.

  • This should be the information that is most important to your users.

  • Don’t put placeholder or arguably pointless text here like
    “Thanks for using the app!”
    “We’re always looking for ways to make things better”
    “ We release every two weeks!”
    “Thank you for your helpful feedback”
    “Bug fixes” (we know you fix bugs)
    That’s precious space you’re filling with words that have no value to the user or your app!

Questions to ask yourself:

  • What is the one thing your users will care most about in this release? 
  • What action do you want to invite them to take?

Examples



Wahoo Fitness does this really well. Right at the top, they list chunky new functionality (who doesn’t love an integration?) and there’s more!



tips app release notes wahoo more.png

‘More’ Additional Detail

This is still contained within the app release notes but can only be seen by scrolling or clicking ‘more’.

Questions to ask yourself:

  • How does the new functionality help them achieve their goals?

  • What have you done to smooth the experience of the app?

  • What did you fix for them, specifically?

Staying with Wahoo Fitness, clicking ‘more’ tells you what’s been updated and improved. The information is likely prioritised according to the user’s needs and provided in a succinct and clean way.



tips app release notes telegram.png

‘More’ Additional Detail Continued

Another app that does this very well is Telegram Messenger. It is nicely formatted and spaced. In addition, it has been written with user goals in mind.



tips app release notes trello.png

‘More’ Additional Detail Continued

And lastly, I want to give a shout at to Trello because I think someone who really cares about the users wrote the release notes (as you might expect from an Atlassian company!):



tips app release notes pluralsight.png

Everything Else

This is right at the bottom of the text and is usually 1–2 lines that can signpost the user in case they have another query.

Questions to ask yourself:

  • Is there any other relevant release information such as compatibility?

  • How can the user get help, support or contact information?

One company that I think nailed it is Pluralsight. They’ve given the most important stuff first and followed it with what they’ve improved. They’ve given details about the bugs and signposted the user to an email address if required. Nice work!

Summary

  • Write with the user goals in mind, always ⚽

  • Give the user the right level of detail in the right place at the right time ✍️

  • You have limited space, make every character count (check out your voice and tone guide) 🔡

  • Consider signposting the user at the end of your app release notes ➡️

  • I personally think we can do away with stating things like “bug fixes” unless you’re going to give details on which bugs. All software companies fix bugs 🐛

Stop Calling them Soft Skills

I’ve had a bee in my bonnet about the phrase ‘Soft Skills’ for as long as I can remember. I can recall thinking, and indeed being told, that ‘Soft Skills’ are super important and I needed to master them if I was going to succeed in life. Oddly very little emphasis was put on ‘Hard Skills’.

I’m pleased to report that I still have no clue as to what succeeding in life looks like (leave a note here if you know). In addition, I recently realised that despite me hating the phrase ‘Soft Skills’, I’d not taken the time to work out why I hated it. This is what I set out to do here. Hopefully, I will also make you think twice about using the phrase in the process. The same goes for ‘Hard Skills’ but that stirs up less irritation for most.



soft skills rocks.jpg

First up, hard and soft are used as adjectives in this context. Hard conjures up notions of challenging or effort. 

Soft conjures up notions of agreeable and smooth. Quite a contrasting picture!

In order to understand why we should stop calling them ‘soft skills’, first, we need to know what they are. If you’d have asked me 20 years ago for examples of ‘soft skills’, I would have reeled off a list like:

  • Communication, Empathy, Respect, Integrity, and Authenticity (to name but a few)

When I started to really think about this, I came to the conclusion that I didn’t really know what a ‘soft skill’ was. Like all self-respecting human beings who are seeking information in the information cesspool of the digital age, I turned to trusty Wikipedia (that never lies, right)?

Image by Gidon Pico from Pixabay 



soft hard skills equal.png

Apparently, Soft Skills are:

…a combination of people skills, social skills, communication skills, character or personality traits, attitudes, career attributes, social intelligence and emotional intelligence quotients, among others, that enable people to navigate their environment, work well with others, perform well, and achieve their goals with complementing hard skills.

Hard Skills, for completeness, are:

… also called technical skills, are any skills relating to a specific task or situation. It involves both understanding and proficiency in such specific activity that involves methods, processes, procedures, or techniques.

I read these definitions multiple times before I realised what irked me. The definitions imply that ‘soft skills’ are easy and somehow less relevant, and indeed less valued, than ‘hard skills’.

Furthermore, the ‘soft skills’ all are behaviours and there is nothing soft about them! They’re HARD!

So with that in mind, what if we call them what they are?

What if we stopped calling them ‘soft skills’ and ‘hard skills’ and started called them behaviours and tools instead?

Note: Please don’t call them “technical” tools, that’s just another categorisation that excludes people.



When we take down the barriers and division of skills and call them what they really are we can assign appropriate value and weight to them.

What would you value more? Someone’s behaviours that overlay every single interaction they have? Or someone’s skills at using a machine, something that can be relatively easily taught. Which one of those things sounds hard?

I could go further too and argue that behaviours are needed when learning tools.

These behaviours:

  • Can’t be as easily taught (but they can be taught)

  • Are not deterministic (A + B may or may not always equal C)

  • Are hard to quantify (metrics to measure many of them don’t exist)

  • Are hard to qualify (they appear defined by what hard skills are not)

  • Modifying behaviours for a human being is hard (well I find it so anyhow)

Behaviours take time, passion and practise to master!

So please, stop underselling and undervaluing them, and start investing in them!

If you are interested in learning more about where the notion of Hard and Soft Skills came from, I encourage you can read the US Army Report from 1972 here https://apps.dtic.mil/dtic/tr/fulltext/u2/a099612.pdf.

Technical Writing – Everyone’s an Expert

I was driving to see my Gran the other day musing over recent events when what I can only assume was a Pterodactyl flew across my car, depositing on my windscreen at least three days worth of breakfast, lunch and dinner. I’ve since had to top up my screen-wash.

You know the drill, you’ve spent hours composing what you consider to be beautiful instructions for the product to assist the user in their hour of need. You’ve gone through all the review gates (that you likely set up) and you’re ready to go live.



tw everones an expert seagull.jpg

And then in comes the expert with their swoop and poop. They read your pride and joy, they glance over who’s reviewed it (if you’re lucky) and then they offer forth their opinion, after all, it’s just some words — everyone’s an expert in those!

You don’t see this with code (usually).

You have PRs, someone reviews it, any changes are made and then the PR is approved. Fortunately, not everyone thinks they’re an expert in Java, which is most definitely a good thing! However, words aren’t afforded the same level of respect, everyone can do words, right?

Deep down, during the aforementioned fly-by, you’re cringing. You want to pull up any number of Hemingway quotes, and wave them about, as well as and stamp your feet (maybe just me). Instead, you sigh, make the requested change (because it’s easier than fighting your corner), and then you likely begrudgingly send it back through all the revision gates because what choice do you have?!

So how can you perform a preemptive strike on potential swoopers and poopers (aka, stakeholders) and what can you do if it’s already happened?

Image by Engin Akyurt from Pixabay

Identify your stakeholders

If you’re new to the business or the role, identify your stakeholders, include them early and get them on board. Find out from your colleagues who is a closet Technical Writer and who always has an opinion as well as the regular list of stakeholders that you’re expecting to work with.

You need to identify their drivers, what makes them tick. Have they been left out in the past? Do they feel like they need to “add value” in all areas of the business so they swing by ‘cos words are easy? Do they want to be you? Do they like to have fingers in all the pies? You have to talk to them!

In fact you have to talk to everyone, leave no stone unturned in your hunt for stakeholders. You need to check behind the sofa, under the rug, and most definitely in the box room. You don’t need to make everyone a reviewer (no one has time for that), but you do need to identify the people that not only care, but are in a position to give a sign off on your creations.



tw everones an expert parrots.jpg

Not all of these stakeholder challenges are easy to solve as many of them are outside of your circle of influence if you take them at face value.

However, this is where your skills of taking people on the journey are absolutely invaluable.

Don’t make them all be a tick box quality gate (although some will be just that), instead ask for their opinion early, show that you value their advice, build their trust in you and your ability to do the job.

Stakeholders who have been allowed to invest their time and energy in the creation of the content will become your biggest advocates. Elevate them and enjoy the extra pair of eyes that you control on your timescales.

Image by Vinson Tan ( 楊 祖 武 ) from Pixabay

They still swooped and pooped! 💩

Okay first up, we’ve all been there, do not have a pity-party. It does no one any good and just serves to make you wallow in your own pit of gloom, eat pizza and get that really judgemental message from Netflix.

Instead, pick yourself up and ask yourself why the fly-by happened. I bet that if you really soul searched you could find something that you can directly change and influence that would dramatically reduce this from happening again.

However, we’ve covered that. So now it’s happened, job one (we’re not doing that pity-party remember), clean up! Now I don’t mean like a Roomba would when the dog deposits a gift in the kitchen; don’t go smearing it everywhere. Instead, graciously pick it up, examine it (I am regretting using this analogy now), deposit it in the nearest bin, and wash your hands (‘cos, eww gross).

Now you need to engage with the pooper to explain what you’re going to do to address not only their concerns with your creation, but future ones. For this one, I strongly recommend that you try and avoid jumping into defensive mode. Signs that you’re in that mode include the urge to explain your processes, justify your methods or wave other reviewer’s feedback at them. If you find yourself there (we all have, I certainly have), take a step back and ask yourself what you want from the situation. What you want is a stakeholder that is your ally early on in the process.



Instead of being the defensive Technical Writer who feels like they now need to justify their efforts, try having an open conversation of asking them why they gave you the feedback, and then keep asking why (in a non-aggressive way). Keep drilling down until you reach the source of their pooping ideology. Channel your inner two-year old self that drove your parents mental with your constant questions.

Once you know the source of their pooping ideology you’ll know what to do with the gift. It may be that while delivered poorly, the feedback is actually crucial and needs incorporating for reasons you didn’t even realise. It may be that they know something you don’t and while it doesn’t need rehashing this time, their ill-timed feedback will save you a lot of pain in other projects.

Alternatively, it may be that they just can’t help themselves, in which case early involvement will likely save you a lot of pain just before release day.

Image by TheOtherKev from Pixabay

When all is said and done, stakeholders who review your content (invited, or otherwise) are both your biggest advocates, and at times, your worst nightmare. Take a step back, ask why they’re giving the feedback and then turn it around so it’s on your terms next time. It’s your content, you’re the Technical Writer. Own it and accept that it is, and always will be, a shared vision.

How do you get into Technical Writing?

Or Technical Authoring, whatever 😉

I realised the other day that despite nearly twenty years in various roles in technical writing, and more recently product, I’ve never written a blog or shared some of the experiences. I’m now going to attempt to rectify this behaviour!

So let’s start back at the beginning with the age-old question — how do you get into technical writing? Well, you fall into it usually! No, I don’t mean it’s a massive hole, although some days that metaphor is apt, nor do you fill in one of those questionnaires at school and it spits out “hey, you’re gonna be a kick-ass technical writer one day”! Nope, sorry, that’s not true either, it’s never on those forms (for reasons I’m not entirely clear on).

So if not that, then how?

Well, sometimes a well-meaning friend pushes you into it with sage words such as “I think you’d be good at this” or “you kinda suck at your job, you need to try something else” (both of these happened to me).

However, an increasingly common route seems to be somewhat more sneaky and subliminal (but you can make it active if you know it’s what you want!). Imagine that you’re in a role, it’s your dream job, it’s what you’ve studied for, and it’s why you have a student debt that is at least 25% of your prospective future mortgage. One morning, while you’re munching your unbranded flakes of corn, you have the sharp realisation that some unseen force has been at work and you’re now the person that is trusted to not only review product documentation, but also create it because you enjoy it. You do your day job too, (you know, the dream one), but you’re also rather invested in the product documentation.

Wait, what?! I don’t even know how that happened! You carefully place your spoon back into your unbranded flakes of corn and wonder how you got here, what turns you took and why you find documentation, heck, technical documentation at that quite so alluring.

This is a great way to get into technical writing! Position yourself as the go-to person for the product documentation and demonstrate your awesome skills with each and every piece of valuable product documentation you create! Go ahead and create a business case for your dream job, mk II, (if it doesn’t exist yet) and land that technical writing job that maybe you didn’t even know was a thing, let alone your thing.

Are you broken? Nope! But you are a special and unique kind of person that is incredibly passionate about helping the user to achieve their goals when you know deep down that if they’re reading your prose, they’re likely already annoyed and have been failed by the product. Yet you still care, you still want to help champion them, you still see the beauty in the written word, and you want to wield it to solve the user’s challenge and help serve the product.

Good for you!