May the words of power be with you
While we are working on the diary of the developer fuel-plugin, the appearance of which you by majority of votes (43 for, 5 against, 19 abstained), we suggest you read the story of our technical writer Irina Povolotskaya about the recently held Hyperbaton conference. This is a gathering of techpists in which they perform their secret rites (crossed out) - sharing their experiences with each other. Since each OpenStack contributor must be able not only to write code, but also to explain to the community why this code has a right to exist, we could not ignore such a significant event. And in general - we have not had updates for a long time. Suddenly you miss?
On April 18, Saturday, the third “Hyperbaton” was held - a conference organized by “Yandex” for technical writers and all those involved in the process of creating documentation.
“Hyperbaton” was held in the office of “Yandex” in Moscow. A toy master Yoda greeted everyone at the entrance to the conference room.
')
For reference : the conference name was chosen by chance: the fact is that the hyperbaton (and not the hyperbat, as it might seem at first glance) is a figure of speech in which words completely magically change the usual order, the favorite technique of the Jedi Order .
When working in open source in general, the ability to describe the programmer motion control gives significant advantages. For example, approval from the team responsible for the integration of partner technologies (as well as advantages in karma and code evaluation) is given to those who are able to clearly describe their actions. If we talk specifically about OpenStack, participation in the developer community 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 it often happens, the organizers especially distinguished themselves. Colleagues from Yandex presented an excellent selection of presentations (you can see them here ) on 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 in Yandex depending on the change in the number of team members - how experience was shared, discussion, tehtolki, tracking tasks.
Alexey Zamulla shared his own impression of mentoring: as it turned out, both the trainer and the trainee benefit from the mentorship. The chance of getting excellent feedback and learning how to manage your time and tasks has increased significantly.
Daria Eremina addressed the topic of immersion in the Big Project, in which, at first glance, it is very easy to drown. Truly, a problem familiar to any technical writer who actively contributes to the OpenStack community - the number of instant messengers, bug trackers, backlogs just goes off scale, and of course you need to keep track of all this and do your immediate work qualitatively: create clear documentation without factual errors. Daria presented the problem as working with different streams: the flow of people, tasks, information, time and, of course, attentiveness. Daria clearly noted that our tasks are sometimes similar to the monkey business, but it is attention to detail that makes the documentation accurate.
Maxim Ilyakhov from Design Bureau Artyom Gorbunov actually conducted a master class, showing with a slight hand movement how to make the text easy, readable, understandable for the user. What is especially nice, he presented a resource for checking the text for the presence of “verbal debris” - unnecessary words and turns, which can be easily thrown out without losing meaning. The most attentive ones found errors in the presentation and received an amusing sticker with a skull and an excellent editorial slogan.
Technical writers asked a lot of topical questions: how to write for specialists, whether to use professional slang; how to motivate technical writers for mentoring and whether it is possible to teach not only beginners, but also each other; whether the technician can find critical bugs and deserve the respect of the developers - these are just the general contours of the discussion.
All this is familiar enough to everyone who contributes to the OpenStack community, or is involved in solving particular problems, as in our case (Fuel and Mirantis OpenStack).
How it works in Mirantis
Technical writers in our company work in multitasking mode, trying with one eye to glance at the upstream, and the other - at local issues, whether it be updating the documentation for the new release or fix bugs.
However, we should not forget about the distinctive feature of Mirantis - the openness of our guides for everyone: anyone can make a change and ask us to comment on the above, suggest the best option or wording. So, mentoring matters to us.
The conference allowed me to reconsider approaches to the solution of our open source tasks and to think about creating additional tools (such as style guides), improving existing ones, and also, perhaps, about a more understandable and transparent process of contributing to the documentation .
Thanks to “Yandex” for the wonderful opportunity to look at the effectiveness of their work from the outside. May the power of words ... be with us all!
If you have encountered problems when describing your work with OpenStack - share your difficulties with us in the comments. And we are happy to devote a separate post to the analysis of typical difficulties and the description of ways to overcome them. Or, maybe, what the hell is joking, we can improve the processes within the ecosystem by formulating suggestions 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 all those involved in the process of creating documentation.
“Hyperbaton” was held in the office of “Yandex” in Moscow. A toy master Yoda greeted everyone at the entrance to the conference room.
')
For reference : the conference name was chosen by chance: the fact is that the hyperbaton (and not the hyperbat, as it might seem at first glance) is a figure of speech in which words completely magically change the usual order, the favorite technique of the Jedi Order .
Why is this important to us?
When working in open source in general, the ability to describe the programmer motion control gives significant advantages. For example, approval from the team responsible for the integration of partner technologies (as well as advantages in karma and code evaluation) is given to those who are able to clearly describe their actions. If we talk specifically about OpenStack, participation in the developer community 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.
Let's go back to Hyperbaton
As it often happens, the organizers especially distinguished themselves. Colleagues from Yandex presented an excellent selection of presentations (you can see them here ) on various aspects of the work of technical writers.
Say what did you want?
Svetlana Kayushina talked about a fascinating experience, I would even say about the evolution of technical writers in Yandex depending on the change in the number of team members - how experience was shared, discussion, tehtolki, tracking tasks.
Alexey Zamulla shared his own impression of mentoring: as it turned out, both the trainer and the trainee benefit from the mentorship. The chance of getting excellent feedback and learning how to manage your time and tasks has increased significantly.
Daria Eremina addressed the topic of immersion in the Big Project, in which, at first glance, it is very easy to drown. Truly, a problem familiar to any technical writer who actively contributes to the OpenStack community - the number of instant messengers, bug trackers, backlogs just goes off scale, and of course you need to keep track of all this and do your immediate work qualitatively: create clear documentation without factual errors. Daria presented the problem as working with different streams: the flow of people, tasks, information, time and, of course, attentiveness. Daria clearly noted that our tasks are sometimes similar to the monkey business, but it is attention to detail that makes the documentation accurate.
Maxim Ilyakhov from Design Bureau Artyom Gorbunov actually conducted a master class, showing with a slight hand movement how to make the text easy, readable, understandable for the user. What is especially nice, he presented a resource for checking the text for the presence of “verbal debris” - unnecessary words and turns, which can be easily thrown out without losing meaning. The most attentive ones found errors in the presentation and received an amusing sticker with a skull and an excellent editorial slogan.
Find out what you wanted?
Technical writers asked a lot of topical questions: how to write for specialists, whether to use professional slang; how to motivate technical writers for mentoring and whether it is possible to teach not only beginners, but also each other; whether the technician can find critical bugs and deserve the respect of the developers - these are just the general contours of the discussion.
All this is familiar enough to everyone who contributes to the OpenStack community, or is involved in solving particular problems, as in our case (Fuel and Mirantis OpenStack).
How it works in Mirantis
Technical writers in our company work in multitasking mode, trying with one eye to glance at the upstream, and the other - at local issues, whether it be updating the documentation for the new release or fix bugs.
However, we should not forget about the distinctive feature of Mirantis - the openness of our guides for everyone: anyone can make a change and ask us to comment on the above, suggest the best option or wording. So, mentoring matters to us.
The conference allowed me to reconsider approaches to the solution of our open source tasks and to think about creating additional tools (such as style guides), improving existing ones, and also, perhaps, about a more understandable and transparent process of contributing to the documentation .
Thanks to “Yandex” for the wonderful opportunity to look at the effectiveness of their work from the outside. May the power of words ... be with us all!
If you have encountered problems when describing your work with OpenStack - share your difficulties with us in the comments. And we are happy to devote a separate post to the analysis of typical difficulties and the description of ways to overcome them. Or, maybe, what the hell is joking, we can improve the processes within the ecosystem by formulating suggestions that colleagues can discuss with the OpenStack Foundation leadership at the Vancouver Summit.
Source: https://habr.com/ru/post/256755/
All Articles