It doesn’t come often that one beautiful summer morning you find yourself in a professional environment among quite a number of accomplished specialists of your bread-and-butter sphere. That you have a chance to acquire invaluable knowledge shared by true masters of their craft. That you build a strong network with your international colleagues for the sake of further cooperation, communication, self-development, and career opportunities.
This June, I jumped on a chance to pay a visit to the Evolution of Technical Communication event (ETC 2016) in Sofia, Bulgaria. So little it would be, if I said that speakers were just great delivering their hot-button topics. Diversity of approaches to speech delivering, quite a range of topics to think over, useful workshops, and marvelous networking organizational skills are to pinpoint when giving a feedback about the conference in Sofia.
My special attention though was heavily attracted by the approaches and techniques applied when producing technical developers’ documentation in the microservices environment. The topic was engagingly presented by Lukasz Gornicki, a technical writer in the past and currently a product owner in SAP Hybris, Poland. Lukasz also conducted a very vivid workshop on the REST API documentation the following day.
It was Lukasz’s professional experience and technical skills that made me try reaching him and find out more.
Lukasz kindly agreed to share some facts and thoughts regarding his career as well as give few tips to those technical writers who are eager to gain efficiency in the technical aspect of the profession.
What has been your career ladder and professional growth at SAP Hybris?
I joined SAP Hybris as a technical writer 5 years ago. Then, I became a documentation architect. For the last two years, I’ve been working as a developing product owner.
What are your current responsibilities on a project?
My current responsibilities and a job title are all about ownership: I am an owner of the part of the product delivered at SAP Hybris. I collect and analyze user feedback about the product, and based on those, the team and I work on improvements to the product. Owning a product means taking both fame and hates from users. As I am a developer as well, my contribution to the team covers also developing features.
What was your technical background at the beginning of your technical writing career?
But programming is not just knowing the syntax or how to write functions. You also need to have a vision of how to structure your code, how to write it so that it’s maintainable in future. And you cannot learn these things from exercises on Java or any other language. It comes with practice and experience. And here my technical writing experience was a perfect match: it helped me with approaching a product and structuring the code. Structuring project’s code is no different than structuring documentation for the product.
What types of deliverables have you been dealing with throughout your technical writing career?
Ever since I started as a technical writer, 90% of my time I spent on creating typical technical documentation: not only API, but also configuration guides, architecture guides, and only few user guides. Back then, it was not about microservices, but a huge monolith that people had to customize on their premises. I wasn’t particularly into writing user guides, as they are all about screen shots. They require lots of efforts to be made neat, and then suddenly you realize that it has been a waste of time, because the UI has changed, design has changed. And no additional time is dedicated to the documentation team for updates. That was a bit of frustration for me.
Now, we’re also creating tutorials and videos on how to use open-source products.
You mentioned that it is very important to feel and be treated as a team member in the dev team. From your own experience, what soft and hard skills might help a technical writer to achieve it?
What really matters in the relationships between technical writers and developers is the fact of actually belonging to the same team: sharing same goals and management.
When it comes to skills, I believe, a person really needs to be open to learning new technologies. Show your dev team that you’re interested in what they do, try to dig a bit deeper into what they deal with. Nobody tells you to become a developer, no. Actually, don’t have to be one to understand what they do. In most cases, developers love explaining how their code works. If you prove them your true interest – you’ll acquire all you need and want to know.
Another important thing to remember is to ask questions whenever something is unclear. Do not feel offended or that you’re losing if you don’t understand something. Be brave, go forward, ask hundreds of questions, and one day you’ll notice that you’ve come to know much more, and the team respects you for your efforts and growth.
In general, what are your recommendations and some best practices that you would apply when creating documentation?
Think of documentation that a user could interact with, not just read it. It applies not only to technical documentation: if it comes to the UI, you can create user guides that your audience can interact with and click through. And if it comes to the technical documentation, it’s even easier – developers would appreciate it, expose their code more, and help you with the content, if it is interactive.
When writing documentation, make sure you can quickly test if it’s still up to date.
I remember when I was working on the core documentation for one of our products, whenever a new feature was completed, developers wrote their own sample projects using their API. I took over the task: started recreating their project from scratch with the help of developers’ instructions. When writing code, I was also writing a set of tutorials (developer tails) with step-by-step instructions using samples from the recreated project. Later on, we made these samples downloadable. Then, I was able to set automated compilation and testing of the project.
Whenever we released something new, we didn’t have to go through documentation line by line to make sure it’s up to date. We were able to run some tests against documentation: trigger a code sample, and if it was going through – that meant that documentation was valid.
The same now, when we write documentation for microservices and cloud: it’s all about simple access to the API through protocols.
You can actually make reading your documentation a really enjoyable process for a user by giving it more interactivity, if it comes to show how your API works.
What are further steps in your career that you are targeted at?
No more career climbing for me. I love doing what I do now. Having had much experience in other companies and other projects, it’s for the first time that I can say I am not bored. Every day there’s something new to learn. I quit my previous jobs because they did not surprise me anymore. And now, when I am a product owner and a developer, I feel that this is what I want to do.
When you are a technical writer, you own the content. You don’t just create and edit it, you gather feedback, you search for ideas on how to improve it. And this is exactly what I do now: it used to be for a small part of the content, and now it is for a bigger product. That’s why I don’t miss the technical writing part yet. Because I still get to write the content and make sure it supplements the product efficiently.
And here comes icing on the cake: Lukasz is going to present the project that he presented at ETC 2016 at TC World in Stuttgart in November 2016. Why should we look forward to it? It allows building a portal and fill it with content stored in multiple various locations. A possibility for other companies and technical writers to build their own documentation portal using their best practices.