My First Hacktoberfest (2020)

I took part in Hacktoberfest this year for the first time. I had a lot of upfront expectations and beliefs. One of these was bang on the money, the rest were so far from the mark it’s a little embarrassing.

What I thought at the start of Hacktoberfest

  • that the process would all be easy

  • that finding a repo to help with would be easy

  • that I would only take me a few hours

  • that I would learn stuff

Hacktoberfest Controversy

It never occurred to me that Hacktoberfest could be a force for bad. I appreciate that might sound naive, but when this blog post was published I was shocked. I read it over and over, trying to make sense of it. I mean, sure, it made sense, now it had been brought to my attention, but in my world, it wasn’t a thing. I simply hadn’t given it any thought. It was eye-opening.

I started questioning myself. I was excited to be participating in Hacktoberfest, but it really made me question if I was doing the right thing. That blog post triggered a change in the rules for Hacktoberfest from Digital Ocean. Repositories then became opt-in to Hacktoberfest which I fervently hope did address the problems highlighted in the earlier blog.

My Experience

So after a somewhat bumpy start and angst, I decided I would still participate in Hacktoberfest because I hoped I would not only add value, but I would also learn stuff. And I like learning stuff!

Job 1 – Find a Repository to Contribute to

Easy right? Nope, not even close. I tried two primary routes here, I browsed the repositories labelled hacktoberfest for hours at a time, there were hundreds. I would whittle them down to Java repositories, then documentation (where I was confident I could add value) and then either the bug would already be assigned to someone, or there would be comments indicating that someone wanted to pick it up. I moved on.

I wasn’t having much luck with this approach, so I considered meetups. This was vaguely successful, but it wasn’t enough. I was painfully out of my depth, and I knew it. I felt like the places I could add value were so small and, even if they existed, I couldn’t find them. I felt utterly defeated.

So we’re now into the second week of October, and all I’d achieved was to get stressed about whether I was doing the right thing participating and, even if I was doing the right thing, I couldn’t find a suitable repository and issue. It wasn’t going great.

Job 2 – Find a different way to achieve Job 1

I’ll be honest, I had a few G&Ts and wondered how on earth I was going to get myself out of my Pit of Doom™️. Then it occurred to me that I had a very obvious option to me that I had not explored. I needed to ask for help. I was incredibly fortunate in many ways in that I had made some contacts in the OSS world before Hacktoberfest 2020. I reached out to a connection and said that I was stuck and I was struggling.

And that’s when my fortune changed. They directed me to a repository where I could add value and a bug too that wasn’t assigned. It was a completely different experience. To be honest, I didn’t realise how little I knew, even then! I took their advice and read the readme. I proceeded to fork the repo, and then clone it into IntelliJ IDEA (obviously). Somehow (still couldn’t tell you how), I managed to run Docker despite knowing nothing about it, and I got the documentation bug fixed up and tested. Go me! I made a PR on the original repo to pull my changes in, and it got accepted. Mind Blown. I never thought I’d make it that far, but I did. I wouldn’t have achieved any of that without help.

I made a couple more PRs using the same repository and Hacktoberfest 2020 is now in the bag. But, I don’t feel as elated as I thought I would. I haven’t been able to put my finger on why, after all, Hacktoberfest has been incredible for my learning. I used it as an opportunity to learn more about the fork-ing, the cloning, the Docker-ing, the PR-ing, the rebasing-of-the-upstream-repo-ing. I probably made too many verbs there, sorry. That was all new to me, and I loved and am grateful for it. I’m annoyed that I waited until Hacktoberfest to do it mind you. I learned so much stuff and, best of all, I’m now a maintainer to that repository. What a fricking honour; I intend to continue to grow and contribute to it outside of the fence of Hacktoberfest.

Takeaways

I was asked on this session what I would tell my younger self next time around for Hacktoberfest. This is my answer (now I’m not under the pressure of a YouTube live stream!):

Do Nots

  • Do not wait until “Preptember” to get ready to contribute to Open Source Software. Do it all year round if you want to.

  • Do not wait until “Hacktober” to offer to contribute to Open Source Software. It was a catalyst for me, yes, absolutely, but I regret waiting.

  • Do not give it all up in “Postvember” (I’m struggling here). Give back. I intend to.

Dos

  • Do attend meetups throughout the year and get to know people. They will be your guiding light throughout the process.

  • Find people who are passionate about it, get to know them and ask them how you can help.

  • Do share your story and your experience. It might help others.

Live Templates in IntelliJ IDEA

Okay, I did the math. If you use all 38 of the Live Templates for Java that are available out of the box in IntelliJ IDEA 2020.2, you will save your finger pads approximately 2092 presses of wear and tear, and that’s just each one once, the reality is likely to be substantially higher. I will caveat this by saying that I counted the unresolved variables, yours may be longer or shorter. Still, it’s impressive!

What are Live Templates?

Java has had its fair share of grief over boilerplate code and verbosity. You could type it out manually (boring), switch to Kotlin (it’s an option), or take a look at using IntelliJ IDEA to save you both time and effort.

When I first came across the notion of Live Templates, I couldn’t figure out what was ‘live’ about them. Did they need feeding or something? It seems to be an industry-standard term, so I’m no longer devoting much energy to this quandary, but if you were wondering the same, you’re not alone.

There are lots of types of live templates in IntelliJ IDEA (38 in fact, as I mentioned). There’s the delightful four-finger taps `psvm` which will expand to 39 finger taps of:

public-static-void-main.png

And another of my favourites, also four-finger taps, is `sout` which expands to 20 finger taps:

system-out-println.png

The Live Templates even determine where the caret appears, which is why screenshots are useful here. There are lots of these ‘non-variable’ Live Templates. They’re quick to use and will quickly embed themselves in your muscle memory. You’ll wonder how you ever wrote:

public static final String

… instead of psfs

However, that’s not all live templates can do; they can also help you with something called ‘parameterised templates’ with variables that you can manipulate.

For example, fori gives you a rather lovely for loop template (29 finger taps):

for-loop-clean.png

By default, IntelliJ IDEA will put the caret on the first instance of i, and this is so you can change it to your preferred variable if required. If you then hit tab, the editor will jump you to the user input part between the less-than symbol and the semi-colon. Tab again will drop you into the body of the loop so you can step away from those arrow keys.

Other live templates for user input constructs include itar to iterate over elements of an array, itco to iterate over elements of a Collection as well as may other iteration operations. lazy is another win, quite literally, to perform a lazy initialisation.

Identifying a Live Template

IntelliJ IDEA is always trying to be helpful. One thing I struggled with was working out what was what when I was typing code. You can spot a live template from the lack of parenthesis and a helpful description. For example, the last four here are live templates, but only one is strictly from Java – fori.

live-template-list.png

Poking around Live Templates

You can take a look at Live Templates from your Preferences using ⌘, on macOS and Ctrl+Alt+S on Windows and Linux then start typing in Live Templates. You’ll see the list split by language. You can have a dig around in here until your heart’s content turning them off (and on again). I found it interesting to check out not only what Java Live Templates there were but also the Live Templates available in the other languages.

Making/Editing/Duplicating a Live Template

Manipulating Live Templates is easy to do in IntelliJ IDEA. As above, find your Live Templates in Preferences and then click this little plus icon:

If you want to duplicate one instead, use the icon a bit further down that looks like paste clipboard.

When you select 1. Live template you can then enter a keyboard abbreviation, a description, and the text that will form your live template.

Live Templates are very flexible in their creation, so here’s a couple of callouts. Firstly, know and use variables wisely. I found these a little bit confusing at first glance, but this documentation removes the mystery nicely and explains what each one does.

Let’s walk through the fori Live Template to see how it breaks down:

for-i-live-template.png

When we use it in a Java class we get this:

for-i-empty.png

How does that work then? Looking back at the Live Template definition, we can see the Edit Variables button. Clicking it yields this information:

edit-template-variables.png

This tells us that the variable $INDEX$ is defined as suggestIndexName() which we can see from the page I pointed you to earlier is defined as:

So $INDEX$ becomes i when we use the Live Template. $LIMIT$ didn’t get a definition in the Live Template so when it’s used in a Java class, that’s where the tab lands for the user to enter a value.

If you leave the value blank, the user can tab to it when the Live Template is used and enter their preferred value, as we saw in the fori example earlier.

Secondly, define your context carefully; this is where the Live Template will be available for use. For example, these are the available Java contexts:

java-contexts.png

Our fori example has a context of Statement which makes sense for a for loop:

for-i-context.png

Now you can go forth and create all the Live Templates that your heart desires and save even more finger taps!

How to Feel Good (about Live Templates)

It’s 2020, to be honest, we all need a little extra help with that warm fuzzy feeling this year. I found this thing called Productivity Guide in IntelliJ IDEA. It doesn’t just cover Live Templates; it covers everything that IntelliJ IDEA does to save your finger pads from wear and tear. Mine is pretty feeble because I have to reset my environment multiple times for various screencasts and stuff. I bet your IntelliJ IDEA statistics are substantially more impressive!

The Java SE Ecosystem

The Java SE ecosystem is strewn with acronyms that it has picked up over the last 25 years. Sometimes those acronyms even mean multiple things. Sometimes there are acronyms within acronyms! This post attempts to explain them all in terms of two main groupings:

  • OpenJDK

  • Java Development Kits (JDKs)

What is ‘OpenJDK’?

The phrase OpenJDK is used to describe at least three fundamental things in the Java ecosystem. I’ve expanded the links here so you can see what I’m talking about.

First

First, there is a place called OpenJDK which lives at https://openjdk.java.net and is also known to some as The OpenJDK Project. This is where people collaborate on an open-source implementation of the Java specifications, https://www.oracle.com/java/technologies/java-se-glance.html, which are released every 6 months. Sun Microsystems open-sourced the majority of Java in 2006 under the GNU General Public License (GNU GPL) version 2 with a linking exception. OpenJDK serves as a continuation of that change. This is the use that I will refer to througout this blog. When I say OpenJDK I mean the place at https://openjdk.java.net unless otherwise specified.

Second

OpenJDK can also refer to just the source code repository on GitHub available at https://github.com/openjdk. This is the reference implementation of the Java specifications that I mentioned above. Many vendors use the term OpenJDK for their specific JDK binary, which is produced by building a binary off the OpenJDK code on GitHub. For example AdoptOpenJDK, which is available at https://adoptopenjdk.net.

Third

Lastly, OpenJDK can also refer to Oracle’s free JDKs which live at https://jdk.java.net. These are version specific binaries built from the source code which is available on GitHub at https://github.com/openjdk. Oracle provides fixes to this JDK for 6 months (until the next release of Java).

Who contributes to OpenJDK?

There are various channels to contribute to OpenJDK. This blog from Oracle has a graphic which breaks down committers for Java 15 – those that committed code to OpenJDK. To contribute to OpenJDK, you need to use a JDK Enhancement Proposal (JEP) to start with.

Correction with thanks to Marc Maathuis: You don’t always need a JEP to contribute to the OracleJDK. Bug fixes, for example may not. Contributors need to have signed the Oracle Contributor Agreement.

What are JEPs?

JDK Enhancement Proposal (JEP) is a proposed change to OpenJDK. You can think of them as the roadmap for Java. Like all good roadmaps, there’s no commitment to inclusion or timescales. Some JEPs require changes to the Java specifications. In this instance, a corresponding Java Specification Request (JSR) is required.

What is a JSR?

A Java Specification Request (JSR) may detail potential specification changes (where present) that arise from one or more JEPs. Not all JEPs will have JSRs; if the JEP doesn’t have changes to the specifications, you don’t need a JSR. A JSR may also be a suggested new specification for Java SE that does not require a JEP, such as a new specification for an API for computer vision. JSRs are considered for inclusion in the Java specifications by the Java Community Process (JCP).

What is the JCP?

The Java Community Process (JCP) is a process to facilitate the review and ultimate inclusion of changes to the Java specifications.

What are JDKs?

Java Development Kits (JDKs) are implementations of the Java SE platform specification by different vendors and groups of people, such as the open source community. Some of them are built from the OpenJDK source code. JDKs include the Java Runtime Environment (JRE), as well as other tools that help you develop Java.

What is the Java Runtime Environment (JRE)?

The Java Runtime Environment (JRE) is a component of the JDK that is required to run Java. It used to be a separate download from the JDK, but, since Java 11, it’s now part of the JDK itself rather than a separate entity meaning you can no longer download it separately.

Are all JDKs the same?

Vendors may introduce little implementation differences such as garbage collection, branding, and utilities, but they are all implementations of the Java platform specifications. For the purpose of this blog I’ve assumed the Java SE platform.

When can you call something a JDK?

To be called a JDK officially, the binaries need to have passed a Java Compatibility Kit (JCK) for that release which is a collection of Technology Compatibility Kits (TCK) that tests each JSR to ensure that the implementation of the specification behaves as expected. Oracle’s OpenJDK we spoke about earlier has passed a JCK, for example.

What’s a Technology Compatibility Kit (TCK)?

A Technology Compatibility Kit (TCK) is a set of tests that is applicable for a JSR. There has been controversy on the license for the TCK given it’s an open source project. There is now a specific license to allow the TCK to be run against the OpenJDK source code under the GPL license.

Who makes JDKs?

There are lots of JDKs out there. They all vary in terms of license, support, branding, and implementation differences. The list includes, but is not limited to AdoptOpenJDK, OracleJDK, Oracle OpenJDK, RedHat, and IBM. It is also possible to build your own JDK too. Talking of blogs, this one from the Java Champions is excellent and helps fill in some of the gaps as to how we got here.

Summary

‘OpenJDK’ is either:

Java Development Kits:

  • A binary which is an implementation of the Java platform specification that has passed a TCK.

  • Some JDKs are free to use, some have a cost associated with them for various things such as commercial use, fixes and support.

Contributions to Java and updates:

  • Anyone can contribute to OpenJDK.

  • The JCP is used to manage updates to the Java specifications. Anyone can join the JCP.

  • JEPs are the process for including changes to OpenJDK.

  • JSRs are the standards for Java SE, which may, or may not be implemented in the JDK itself.

New to IntelliJ IDEA? Me Too.

Until recently, I last wrote Java in anger in 2002. IntelliJ IDEA had just been released; it wasn’t remotely on my radar. I honestly can’t remember what IDE we were using back then, but it certainly was a very long way to the fully featured IDE that JetBrains produce today. Here’s my experience of using IntelliJ IDEA for the first time.

Downloading IntelliJ IDEA

There’s a lot going on when you first load IntelliJ IDEA, but I learned pretty quickly that there are also some good first steps you can take to make your experience a little more comfortable. The first thing I would say is that it’s an enterprise tool so there is a learning curve. There’s no getting around that – it’s the same with any new piece of enterprise software; you do need to give it some time and be willing to go on a learning journey. Fortunately for us, JetBrains have, in my opinion, done a very good job at supporting developers on that learning curve. So, if you’re sitting comfortably, here are my recommendations.

  1. Figure out which version of IntelliJ IDEA you need. I once offended my now-colleague Trisha Gee by asking her which IDE to use because I didn’t know that IntelliJ IDEA Community was free. Foolishly, I assumed that because it was an insanely powerful IDE that it couldn’t possibly be free. I was appropriately schooled by a rather irritated Trisha and told in no uncertain terms that I could use IntelliJ IDEA for FREE. Honestly? Mind blown. I then decided that there must be a catch, so I assumed (see a pattern here?) that it would only be free for me to muck about and not free for commercial development. Wrong again, Helen, wrong again.

  2. Next up, download JetBrains Toolbox, even if you’re only using IntelliJ IDEA. I promise you it’s worth it. This cute little box will sit on your toolbar, chill out and manage all the installs and updates to IntelliJ IDEA with minimal input from yourself. Use your new JetBrains toolbox to download the version of IntelliJ IDEA you require and manage your licensing requirements.

Okay, great! You’ve got a shiny version of IntelliJ IDEA downloaded. Let’s get started!

Running IntelliJ IDEA for the First Time

  1. You’ll be asked to choose between Darcula and Light for your UI theme. I am not getting into this argument. I like light, deal with it. Click Next: Default Plugins to move on (unless you’re in a rush in which case click Skip Remaining and Set Defaults). IntelliJ IDEA does a great job of selecting the plugins that you’re most likely to need – these are the Default plugins. You can disable some of them if you want to but if you’re not entirely sure just leave them because you can tinker with them later.

  2. Click Next: Featured plugins, this is a list of plugins that are the most common ones. Feel free to go rummaging around for plugins, but keep it real – the more plugins IntelliJ IDEA has, the more it has to deal with as well as being your awesome IDE. I recommend you build the plugins up so you get used to IntelliJ IDEA out-of-the-box-almost to start with. With that in mind, you should definitely go ahead and grab Key Promoter X and IDE Features Trainer if you’re new to IntelliJ IDEA (which you probably are given you’re reading this)! Now click Start Using IntelliJ.

Little note here, if you screw up your settings and want to unwrap IntelliJ IDEA all over again, go to File > Manage IDE Settings > Restore Default Settings. This is relatively new and can be a very useful learning experience. 

Starting a New Project in IntelliJ IDEA

  1. I’m going to go ahead and start a new project. Here’s where we need to sort our Java version out. IntelliJ IDEA is pretty smart about this. It will go and look for the Java versions you’ve already got installed, if there are any. If it finds them, it will populate the Project SDK with them. If it doesn’t find any it gives you an option to download them. You can select your Vendor and your Version and click Download. I recommend you leave the default Location because again, IntelliJ IDEA is smart and knows exactly where to look to find what it needs.

  2. You can select additional libraries here if you want to and you know what you want. I am going to leave them blank and click Next.

  3. Next up, we have Templates. You can create templates from existing projects to recreate later, however on new installations the only template available will be Command Line App. This is a boilerplate Java application with a class and a method. If you’re new to IntelliJ IDEA, it’s worth selecting this option just to get a feel for the file structure and inner workings.

  4. Go ahead and enter a Project name. The Project location will be constructed from the name although you can change it if required. If you want to change the Base package you can do but for now, I recommend you go ahead and click Finish.

And there you have it! One shiny new IntelliJ IDEA project!

A Note on the ‘Release Version’

If you’re anything like me, the first thing you do is throw caution to the wind and go change a bunch of settings in the IDE because you ‘know what you’re doing’. Well, turns out, I didn’t! So, word of warning – if you see this error, it means your ‘Project bytecode version’ is set to something higher than your ‘Project SDK’ (and thus Project language level)’:

Java release version not supported

Check your SDK setting by using ⌘; on macOS, or Ctrl+Alt+Shift+S on Windows/Linux and looking at your Project Settings > Project, specifically your Project SDK and Project Language Level values and make a note of them.

Project Structure

Next, check your Project Bytecode version by using ⌘, on macOS or Ctrl+Alt+S and search for Build, Execution, Deployment > Compiler > Java Compiler. Your Project bytecode setting needs to either be the same as your Project language level, or something lower than it, such as Java 11. Then you can rebuild the project.

Java Compiler Setting

Being new to IntelliJ IDEA, something else that I wondered was what’s the difference between the Project SDK and the Project language level. As it turns out, the Project SDK are the tools you need to develop Java (seems fair), whereas the Project Language Level refers to the assistance that IntelliJ IDEA will give you in the editor. The two settings can be different as well. Your Project language level will restrict what inspections IntelliJ IDEA applies to your code and determine which compiler is used to turn your Java code into bytecode. You can override the compiler settings as I showed above if you don’t want to compile your code with the Project Language Level.

Summary

I can remember hating getting my environment set up at university – and I screwed it up regularly too. There is absolutely no doubt that IntelliJ IDEA makes the whole process of running ‘HelloWorld.java’ a whole lot easier. It does a great job of obfuscating the settings until you need them and will hold your hand throughout the process of setting up your environment without you breaking into a sweat about your classpath setting. Yes, you can break it, but you can also fix it very easily.

The discussion of whether to use an IDE, or not, is one that polarises people. As someone returning to Java after a long period of absence, working with an IDE of this calibre is like having a really knowledgeable friend help you achieve your goal (to run HelloWorld.java) and just that, as quickly and as efficiently possible. I know I’m still scratching the surface of what IntelliJ IDEA can do, but I’m a huge fan of the right information at the right time (which is when I need it) and IntelliJ IDEA does this very well. I’m looking forward to finding out more!

Java, Where Are We Now?

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!

Duke

Duke

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.