Before the last month I hadn’t written any Java in anger in 20 years. My professional path took me into the world of communicating and away from programming. Now it’s converged again as I embark on my developer advocacy journey. One of the things that I’ve already learned is that the Java world has changed, a lot. This blog gives you a whirlwind tour of the last 20 years, specifically with ownership and versions.
When I skipped town, Java was owned by Sun Microsystems and incrementing versioning in a fairly standard way. They started with 1.0 JDK in 1996, then 1.1 JDK in 1997, it became J2SE at version 1.2 in 1998, moving to 1.3 in 2000, and then 1.4 in 2002. You get the idea. Imagine my surprise when they jumped to Java SE 5.0 in 2004.
Now there’s one really important point here that I know if I don’t mention it I will officially be “wrong on the internet”. There is a difference between what Sun called Java to the masses and what it really was underneath. For that reason I’ve distinguished between the marketing name and the version that would have been returned had you asked Java what version it was in the following diagrams. The text uses the marketing name for ease of reading.
Another two years went by, and we ushered in Java SE 6 in 2006 – this release didn’t have a minor version either, just 6, outwardly at least. There was then a strange lull until 2011 (that’s 5 years!) before we said hello to Java SE 7. This gap is at least partly explained by Oracle Corporation buying over from Sun Microsystems on the Java front. Java has had its fair share of criticism when it comes to the speed of its growth, I presume in part due to this lull.
However in 2011 Java 7 landed and the world moved on again. I got married in that lull and learned that real adulting largely involved early nights and paying bills. Apparently you can’t get by on 4 hours sleep and a large quantity of wine.
The unstable cadence of releases continued for a bit with Oracle at the helm, but 2014 brought us a huge release in the form of Java 8. Oracle also labelled this a Long Term Support (LTS) release, which means that there are some licensing implementations for the OracleJDK which I’ll cover in a future post.
Another couple of years went by, I found out that I liked lifting weights, and in September 2017 we saw Java SE 9 with Java SE 10 hot on its heels in March 2018. Wait a minute! Did you just say 6 months between a release? Yes, yes I did.
And that’s why, in 20 years we were now almost on Java SE 15; Oracle’s model of releasing is every 6 months. It doesn’t matter what is in there, they will categorically release Java every six months and they will increment the whole version number when they do so. Whatever functionality is finished goes in. I will cover exactly how functionality gets into Java in a future post.
At time of posting we’re rapidly marching towards the September 2020 release of Java SE 15! Java has changed, a lot. It has grown, it has matured and it’s stronger than ever. That makes two of us!
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!
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. 🥑
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!
…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!
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!
‘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.
‘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.
‘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!):
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 🐛
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.
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)?
…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.
… 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!
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.
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?
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.
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.
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.
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.
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.
