May words be with you words
While we are working on a diary of a fuel plug-in developer, whose appearance you approved by the majority of votes (43 - for, 5 against, 19 - abstained), we suggest you read the story of our technical writer Irina Povolotskaya about the recent Hyperbaton conference. This is a collection of technical books on which they perform their secret rites (crossed out) - share experiences with each other. Since each OpenStack contributor must be able to not only write code, but also explain to the community why this code has a right to exist, we could not ignore such a momentous event. And in general - for a long time we did not have updates. Suddenly you are bored?
On April 18, Saturday, the third “Hyperbaton” was held - a conference organized by Yandex for technical writers and everyone involved in the process of creating documentation.
“Hyperbaton” was held in the office of “Yandex” in Moscow. At the entrance to the conference hall, toy master Yoda greeted everyone.
For reference : the conference name was not chosen by chance: the fact that ISU e rbaton (not Hyperbatas of the district, as it might seem at first glance) - a figure of speech in which the words are magically change the usual order, a favorite method of the head of the Order of the Jedi .
When working in open source in general, the ability to describe the programming movement provides significant advantages. For example, approval from the team responsible for integrating affiliate technologies (as well as pluses in karma and code evaluation) is received by someone who is able to clearly describe their actions. Speaking specifically about OpenStack, participation in the community of developers requires not only the ability to write code. The ability to logically and briefly describe what you are doing, to justify the need for your work, has a huge impact on the success of an initiative .
As often happens, the organizers were especially distinguished. Colleagues from Yandex presented an excellent selection of presentations (you can see them here ) devoted to various aspects of the work of technical writers.
Svetlana Kayushina talked about a fascinating experience, I would even say - about the evolution of technical writers at Yandex depending on the change in the number of team members - how the experience was exchanged, discussions, technical explanations, task tracking.
Alexey Zamulla shared his own impression of mentoring: as it turned out, both the training and the trainee benefit from mentoring. The likelihood of getting excellent feedback and learning how to manage your time and tasks has increased significantly.
Daria Ereminaturned to the topic of immersion in the Big Project, in which, at first glance, it is very easy to drown. Truly, a problem that is familiar to any technical writer who actively contributes to the OpenStack community - the number of instant messengers, bug trackers, and backlogs is just off the charts, and of course you need to follow all this and do your direct work qualitatively: create understandable documentation without actual errors. Daria presented the problem as working with various flows: the flow of people, tasks, information, time and, of course, attentiveness. Daria absolutely definitely noted that our tasks are sometimes similar to monkey business, but it is attention to detail that makes the documentation accurate.
Maxim Ilyakhovfrom Design Bureau Artyom Gorbunov actually held a master class, showing with a flick of the wrist how to make the text easy, readable, understandable for the user. What is especially pleasant, he presented a resource for checking the text for the presence of “verbal garbage” - unnecessary words and phrases that can be easily thrown out without losing meaning. The most attentive found errors in the presentation and received a funny sticker with a skull and a wonderful editorial slogan.
Technical writers asked a lot of relevant questions: how to write for specialists, whether to use professional slang; how to motivate tech writers to mentor and whether it is possible to teach not only beginners, but also each other; can a tech writer find critical bugs and earn the respect of developers - these are just the general contours of the discussion.
All this is quite familiar to everyone who makes a feasible contribution to the OpenStack community, or is engaged in solving private problems, as in our case (Fuel and Mirantis OpenStack).
How it works in Mirantis
Technical writers in our company work in multitasking mode, trying to glance upstream with one eye and local issues with the other, be it updating documentation for a new release or fixing bugs.
However, we should not forget about the distinctive feature of Mirantis - the openness of our guides to all comers: anyone can make a change and ask us to comment on the above, offer the best option or wording. So the issues of mentoring are of great importance to us.
The conference allowed me to reconsider approaches to solving our open source problems and think about creating additional tools (such as a style guide), improving existing ones, and, possibly, a more understandable and transparent process of contributing to the documentation .
Thanks to Yandex for the wonderful opportunity to look at the effectiveness of your work from the outside. May the force be with us all ... words!
If you have encountered problems describing your work with OpenStack, please share your difficulties with us in the comments. And we will be happy to devote a separate post to the analysis of typical difficulties and the description of ways to overcome them. And maybe, damn it, we can improve the processes within the ecosystem by formulating proposals that colleagues can discuss with the OpenStack Foundation leadership at the Vancouver summit.
On April 18, Saturday, the third “Hyperbaton” was held - a conference organized by Yandex for technical writers and everyone involved in the process of creating documentation.
“Hyperbaton” was held in the office of “Yandex” in Moscow. At the entrance to the conference hall, toy master Yoda greeted everyone.
For reference : the conference name was not chosen by chance: the fact that ISU e rbaton (not Hyperbatas of the district, as it might seem at first glance) - a figure of speech in which the words are magically change the usual order, a favorite method of the head of the Order of the Jedi .
Why is this important to us?
When working in open source in general, the ability to describe the programming movement provides significant advantages. For example, approval from the team responsible for integrating affiliate technologies (as well as pluses in karma and code evaluation) is received by someone who is able to clearly describe their actions. Speaking specifically about OpenStack, participation in the community of developers requires not only the ability to write code. The ability to logically and briefly describe what you are doing, to justify the need for your work, has a huge impact on the success of an initiative .
Back to Hyperbaton
As often happens, the organizers were especially distinguished. Colleagues from Yandex presented an excellent selection of presentations (you can see them here ) devoted to various aspects of the work of technical writers.
What did you want to say?
Svetlana Kayushina talked about a fascinating experience, I would even say - about the evolution of technical writers at Yandex depending on the change in the number of team members - how the experience was exchanged, discussions, technical explanations, task tracking.
Alexey Zamulla shared his own impression of mentoring: as it turned out, both the training and the trainee benefit from mentoring. The likelihood of getting excellent feedback and learning how to manage your time and tasks has increased significantly.
Daria Ereminaturned to the topic of immersion in the Big Project, in which, at first glance, it is very easy to drown. Truly, a problem that is familiar to any technical writer who actively contributes to the OpenStack community - the number of instant messengers, bug trackers, and backlogs is just off the charts, and of course you need to follow all this and do your direct work qualitatively: create understandable documentation without actual errors. Daria presented the problem as working with various flows: the flow of people, tasks, information, time and, of course, attentiveness. Daria absolutely definitely noted that our tasks are sometimes similar to monkey business, but it is attention to detail that makes the documentation accurate.
Maxim Ilyakhovfrom Design Bureau Artyom Gorbunov actually held a master class, showing with a flick of the wrist how to make the text easy, readable, understandable for the user. What is especially pleasant, he presented a resource for checking the text for the presence of “verbal garbage” - unnecessary words and phrases that can be easily thrown out without losing meaning. The most attentive found errors in the presentation and received a funny sticker with a skull and a wonderful editorial slogan.
Find out what you wanted?
Technical writers asked a lot of relevant questions: how to write for specialists, whether to use professional slang; how to motivate tech writers to mentor and whether it is possible to teach not only beginners, but also each other; can a tech writer find critical bugs and earn the respect of developers - these are just the general contours of the discussion.
All this is quite familiar to everyone who makes a feasible contribution to the OpenStack community, or is engaged in solving private problems, as in our case (Fuel and Mirantis OpenStack).
How it works in Mirantis
Technical writers in our company work in multitasking mode, trying to glance upstream with one eye and local issues with the other, be it updating documentation for a new release or fixing bugs.
However, we should not forget about the distinctive feature of Mirantis - the openness of our guides to all comers: anyone can make a change and ask us to comment on the above, offer the best option or wording. So the issues of mentoring are of great importance to us.
The conference allowed me to reconsider approaches to solving our open source problems and think about creating additional tools (such as a style guide), improving existing ones, and, possibly, a more understandable and transparent process of contributing to the documentation .
Thanks to Yandex for the wonderful opportunity to look at the effectiveness of your work from the outside. May the force be with us all ... words!
If you have encountered problems describing your work with OpenStack, please share your difficulties with us in the comments. And we will be happy to devote a separate post to the analysis of typical difficulties and the description of ways to overcome them. And maybe, damn it, we can improve the processes within the ecosystem by formulating proposals that colleagues can discuss with the OpenStack Foundation leadership at the Vancouver summit.