Respect the introvert!
a follow-up to the #apithedocs conference in Amsterdam
I’m always the chatty one, the one who goes and talks to people (I blame my Belarusian roots). Not this time. I felt I didn’t want to be disturbed in any way this time. Suddenly, I was the introvert the host was asking not to bother. Yeah, he actually said it politely in the intro of the conference to respect the introverts and leave them alone.
That’s a first.
I took advantage of the situation. It felt good for a change to be set free from the social aspect of gatherings of like-minded people. This event made it possible for me to meet my inner introverted being (a true Estonian?) over a very long time. It’s all about balance, right?
Sitting alone and not talking to anybody didn’t feel weird at all, as a matter of fact it was very comfortable, because after a short observation I noticed I wasn’t the only one.
Being the only technical writer at Pipedrive often makes me feel like a unicorn — is my work real? Does my work add value? I’m still struggling to explain my daily job to my friends and relatives, mostly because I go too technical too quickly. But I’m the one who's supposed to explain difficult things in a simple human language, no? Yes, yes, I am.
The #apithedocs conference was the first time in my tech writer’s career when I saw other unicorns in the same room altogether there for the same purpose — to write awesome docs. Our Docs in Pipedrive is still pretty young, and pretty… well… small. Strong, but small. There’s tons of things to do for improvement.
Almost two months have passed from the #apithedocs conference and I thought I’d give you the main takeaways which I actually still carry with me to this day for the sole purpose of improving our Docs.
We’re already heading the right direction — I communicate with developers on a many-times-a-day basis
One of the presenters asked attendees to raise their hands when he wanted to know who communicates to developers on monthly/weekly/daily/many times a day basis. I and this other person were the only ones with their hand held high for the last one.
I felt proud.
I visualised the feedback process and improved it
I used to copy the finished article link from Confluence and paste it to #all-devs Slack channel asking for a review. After the conference, I decided to treat the articles by the endpoints/information/data applied in the tutorial, find the team/developer responsible for it, and ask for their help instead of relying solely on our team's developers.
writer != reader — I have to be able to fit both roles
It’s easy to get lost in the article I’m writing. It’s even easier to forget that the reader might not have the same background and information I have gained while writing, and communicating with different people involved. Now, once the article has gone through all the stages of the review process, I step away from it for some time and read it again afresh prior to inserting the content to pipedrive.readme.io/docs and making it publicly accessible.
We started with a skateboard
We didn’t try to put out a Porsche Panamera as the first version of our Docs (which would have taken a lot-lot longer and been obsolete already before going live). Instead, for our “MVP” of Docs, we built a nice and solid Birdman skateboard, which took less time and is decent enough to get the user from point A to point B. The reader has to do a little more work compared to the best version on the market, but it’s a perfect base to start building upon it according to the feedback and requests from the readers.
What is DX? Developer Experience
Cristiano Betta said that while UX is hard, DX is way harder, so he provided 7 DX sins and 7 tricks to tackle them:
- Too much information — Prevent cognitive overload
- Information that comes too soon — Only ask questions when needed
- Too little, too late information — Present information on time
- Unstructured information — Present information with structure
- Unsupportive information — Tell the best stories
- Incomplete information — Tell the whole story
- Out of control tooling — Own the whole story
#sorrynotsorry
Although we’re doing pretty good in the communication department, it hasn’t always been easy for me to go and bother people with all these questions all the time. I shouldn’t worry about it + I shouldn’t doubt the skill of decision making of whoever says one has the time to help me.
Of course, the above mentioned is not all of it (see the API the Docs Amsterdam page for the videos, slides and text recaps). Awesome tips and tricks were flying around the venue throughout the day and luckily I’m an avid note-taker. Nevertheless, in times of information overload, it’s pretty tricky to grasp and apply all at once, but I’ll give it my best.
All in all, seeing other unicorns somehow made it more real and made me realise that I’m adding more value with my work than I first thought.
Here’s a perfect place to thank each and every one of you who have helped to write awesome Docs —
I couldn’t do this without you!
