Interview with Anne Gentle, Documentation Development Coordinator for the OpenStack Community
We present the sixth of a series of interviews with technical leaders of the OpenStack project in the Mirantis blog. Our goal is to educate the wider technical community and help people understand how they can contribute to and benefit from the OpenStack project. Naturally, below is the point of view of the interviewee, not of Mirantis.
Below, we present an interview with Anne Gentle, coordinator for the development of documentation for the OpenStack community.
Mirantis: Tell us about yourself.
')
Anna Gentle: I work on the staff of Rackspace and write OpenStack documentation. I am the second employee that Rackspace has hired specifically to work with OpenStack. It was a happy occasion for me. In 2009, I wrote a book about how to work together on documentation in the community, and I repeatedly participated in creating documentation for open source projects. And so this work appeared, right next to my house, in Austin (Texas), and I clutched at it.
Q: What is the key difference between open source and closed source documentation?
Answer: The first big difference is the interest in openness in everything, from documentation development tools to publication. In the first week of work, I was even asked if all our fonts were used on the principle of open source! Our tools are open to everyone - you can freely write documentation or compose parts or reuse texts. The second difference is the documentation itself. In a closed source, documentation is limited to legal requirements in terms of compliance with service level agreements or billing. The idea behind open, collaboratively developed documents is that anyone can edit them. Also in some communities there is a certain ethics in determining authorship of content. This is a good script for Creative Commons licenses (attribution).
There is a wide range of projects, but most of the options are related to licensing and the freedom to handle content. I also believe that many interesting innovations occur in open source projects. For the same reasons that you develop open source, people want to participate in the joint development of documents.
Question: What is special about openly developed documents?
Answer: When developing documentation, discipline is important, and open design, oddly enough, self-organizes. Projects where documents are as tied to the code as possible are usually very disciplined. You find a mistake in the documentation, but people can take it for correction.
Over time, wiki systems became more organized and turned into content management systems, and real free wiki systems based on the original idea of ​​Ward Cunningham are still a very valuable mechanism and valuable idea of ​​working with content. More than wiki-systems, I like innovative documentation development sessions, such as sprint methods (Book Sprint). I also like the attitude to documents as a code, the search for ways to automatically generate documents that help users and correspond to the code.
Question: What principles are applicable to open source documentation?
Answer: Open documentation development is a process in which both discipline and diplomacy are present. You need to find ways to implement the procedure for developing documentation, but at the same time be very diplomatic, because people add content and appreciate it and want it to exist in its official form.
One of the most interesting methods is Book Sprint. You gather a group of writers, organize the exchange of knowledge and try to select an organized structure from the whole array. Using the Booktype tool, it’s very cool that Sourcefabric can support an instance for you.
When developing the Process Manual, everyone who attended the sprint knew how to use our XML-based tools, and then was able to use Booktype immediately, and then, after the sprint, when the content settled down and gained weight, we implemented it into a number of tools on XML based.
The cool thing about XML-based tools is that they are used by O'Reilly. The value of XML is that it allows us to reuse chunks of content, tag them or avoid duplicate translations. From the pieces of content you can then get a lot of output documents. We can get an ePub if we want. And then, as you work with content, you realize that this type of XML-based partitioning is the best way to comprehend the immense and organize it.
Documents are embedded in code development techniques. We use git. We use gerrit. We check each other's texts, by analogy with editing a code fragment. The code snippet must be created locally, then make sure that it got into the assembly and passed the test. Jenkins checks all our texts and automatically publishes.
One of the fundamental principles is that you do not want to annoy or discourage your approach to documentation. People are looking for groups that are similar to them. You can say: “No, these are not my people” or “This is not my area of ​​interest.” One of the principles of open development of documentation for me is personal interaction. People need to understand that it is their own, that they have common goals.
I try to relate work and competence so that you don’t give up and leave. What tasks are interesting for you from a technical point of view? I think one of the fundamental principles of open development is the consistency of people and tasks.
Q: Do you see differences in contributions to the OpenStack documentation depending on people's experience?
Answer: For the Grizzly release, 50 percent of all edits, with the exception of books describing the API interface, were performed by three people, including me (laughing). But we are trying to attract more people to more work.
But the most interesting is that we had 79 project participants in general. These people made six or eight patches, but they also had special knowledge. They knew how to set up Cinder, what was needed to be done, how much of the content needed to be written in order to realize their plans.
You need a core group that knows everything about all the fragments in the database or in its main part, but you also need narrow specialists. With the growth of the project it is important to determine the priorities - whether to stay at a high level or work from project to project.
There are instructions for administrators for each project, but they should still contain instructions for installing and configuring software. The storage guide contains a bunch of information known only to employees involved in drivers. Indeed, it is difficult to determine whether it is necessary to maintain administrative guidelines for each project. Now in work 10 projects and 2 more projects are considered. We can’t support 10 admin guides, especially if some of them are interrelated. We explore and look for the best way to a) attract participants, but also b) help them find a project for work.
There is another aspect - we want developers to write for developers, etc. The Book Sprint methodology revealed to me that the Process Manual worked because its authors perform these processes every day. I see the same thing in the security hardening guide; these guys breathe and live this topic.
Question: What keeps people from contributing to the documentation and from participating in it?
Answer: I think many people see that we use GitHub, Gerrit and XML and think, “Oh, this is not our specialty!” ... and move away. I introduced dozens of people who signed a member's license agreement (CLA). You have to be patient enough to go through this, since you are just writing documentation or you want to correct a typo, but you must go through the entire process of signing the CLA agreement. And I have the firm conviction that it is needed. I prefer the authors of documentation who participate in the OpenStack Foundation and the open source community, rather than random people.
And finally, the sheer volume of knowledge and hardware and hardware requirements can scare people away.
Q: What is the path to go from beginner to professional in terms of documentation in OpenStack?
Answer: There are a couple of possible paths. Be sure to try working with OpenStack, and then see which audience is yours. Then start by studying the documentation: “Does she answer my questions? Are there any missing fragments? ”And make sure that you try on the role of a user or developer when you read the document.
I think user groups are starting to do really cool things. Sean Roberts and Colin McNamara are leaders of the San Francisco Bay User Group, and they conduct a small workshop on how to write documentation, because there are people who want to master OpenStack, and one of the best ways to learn is to learn tools and documents. And a great way to learn is to record what you are doing.
We also have many groups of students who think something like, “I think the documentation is a good starting point.” For them, we have a list of tasks. See if there is any introductory information in the book. Perform a spell check. Check the text for capitalization rules, etc.
I also think that people can rate documents. Some people sent me a PDF with edits. And this is absolutely normal. Anything to start reading, evaluating, choosing what they can extract from this vast array of documentation, “Oh, this is where I can start.”
Question: Tell us about the camp for the preparation of authors of documentation?
Answer: Our training camp is a way to build connections between participants and encourage more people to participate in key documentation. We have it in Mountain View, California, on September 9 and 10.
We go through all the tools and processes so that everyone masters the tools sufficiently. For processes, we will answer questions like “Do I need to write a draft for this? Or is it just a mistake? How do I determine what to do? How do I choose a tool to check? What is a maven? When I add a new book, what should I do to publish it? How can I diagnose if I made a change, but I do not see it on the site? ”This is all on the first day.
And on the second day, this is more of a conversation, where we are talking about what you can work on. You do not have to go to work right that day, but many people say, “This is what we can actually do with the knowledge that we have now received.” On the second day, we eliminate documentation errors. The basic idea is that new members be immediately integrated into the core of documentation developers.
Question: What about translations?
Answer: The real value for me is, for example, that one day the OpenStack manual will be written in French, and instead of translating from English into French, there will be a reverse translation. I don’t think English should always be used as a source language. This is my personal opinion, but I don’t think that your first OpenStack manual is to have English manual.
Translation of documentation comes down to prioritization. The first priority for us is the translation of the process manual, since it is in greatest demand. Daisy, the translation coordinator, asked me last week what to translate next. And I answered: “To be honest, I would like to see this user guide translated, possibly after the Administrator’s Guide. We will try to reach the audience of operators and administrators in their language. ”
Question: Thank you for your time.
Answer: Thank you.
Below, we present an interview with Anne Gentle, coordinator for the development of documentation for the OpenStack community.
Mirantis: Tell us about yourself.
')
Anna Gentle: I work on the staff of Rackspace and write OpenStack documentation. I am the second employee that Rackspace has hired specifically to work with OpenStack. It was a happy occasion for me. In 2009, I wrote a book about how to work together on documentation in the community, and I repeatedly participated in creating documentation for open source projects. And so this work appeared, right next to my house, in Austin (Texas), and I clutched at it.
Q: What is the key difference between open source and closed source documentation?
Answer: The first big difference is the interest in openness in everything, from documentation development tools to publication. In the first week of work, I was even asked if all our fonts were used on the principle of open source! Our tools are open to everyone - you can freely write documentation or compose parts or reuse texts. The second difference is the documentation itself. In a closed source, documentation is limited to legal requirements in terms of compliance with service level agreements or billing. The idea behind open, collaboratively developed documents is that anyone can edit them. Also in some communities there is a certain ethics in determining authorship of content. This is a good script for Creative Commons licenses (attribution).
There is a wide range of projects, but most of the options are related to licensing and the freedom to handle content. I also believe that many interesting innovations occur in open source projects. For the same reasons that you develop open source, people want to participate in the joint development of documents.
Question: What is special about openly developed documents?
Answer: When developing documentation, discipline is important, and open design, oddly enough, self-organizes. Projects where documents are as tied to the code as possible are usually very disciplined. You find a mistake in the documentation, but people can take it for correction.
Over time, wiki systems became more organized and turned into content management systems, and real free wiki systems based on the original idea of ​​Ward Cunningham are still a very valuable mechanism and valuable idea of ​​working with content. More than wiki-systems, I like innovative documentation development sessions, such as sprint methods (Book Sprint). I also like the attitude to documents as a code, the search for ways to automatically generate documents that help users and correspond to the code.
Question: What principles are applicable to open source documentation?
Answer: Open documentation development is a process in which both discipline and diplomacy are present. You need to find ways to implement the procedure for developing documentation, but at the same time be very diplomatic, because people add content and appreciate it and want it to exist in its official form.
One of the most interesting methods is Book Sprint. You gather a group of writers, organize the exchange of knowledge and try to select an organized structure from the whole array. Using the Booktype tool, it’s very cool that Sourcefabric can support an instance for you.
When developing the Process Manual, everyone who attended the sprint knew how to use our XML-based tools, and then was able to use Booktype immediately, and then, after the sprint, when the content settled down and gained weight, we implemented it into a number of tools on XML based.
The cool thing about XML-based tools is that they are used by O'Reilly. The value of XML is that it allows us to reuse chunks of content, tag them or avoid duplicate translations. From the pieces of content you can then get a lot of output documents. We can get an ePub if we want. And then, as you work with content, you realize that this type of XML-based partitioning is the best way to comprehend the immense and organize it.
Documents are embedded in code development techniques. We use git. We use gerrit. We check each other's texts, by analogy with editing a code fragment. The code snippet must be created locally, then make sure that it got into the assembly and passed the test. Jenkins checks all our texts and automatically publishes.
One of the fundamental principles is that you do not want to annoy or discourage your approach to documentation. People are looking for groups that are similar to them. You can say: “No, these are not my people” or “This is not my area of ​​interest.” One of the principles of open development of documentation for me is personal interaction. People need to understand that it is their own, that they have common goals.
I try to relate work and competence so that you don’t give up and leave. What tasks are interesting for you from a technical point of view? I think one of the fundamental principles of open development is the consistency of people and tasks.
Q: Do you see differences in contributions to the OpenStack documentation depending on people's experience?
Answer: For the Grizzly release, 50 percent of all edits, with the exception of books describing the API interface, were performed by three people, including me (laughing). But we are trying to attract more people to more work.
But the most interesting is that we had 79 project participants in general. These people made six or eight patches, but they also had special knowledge. They knew how to set up Cinder, what was needed to be done, how much of the content needed to be written in order to realize their plans.
You need a core group that knows everything about all the fragments in the database or in its main part, but you also need narrow specialists. With the growth of the project it is important to determine the priorities - whether to stay at a high level or work from project to project.
There are instructions for administrators for each project, but they should still contain instructions for installing and configuring software. The storage guide contains a bunch of information known only to employees involved in drivers. Indeed, it is difficult to determine whether it is necessary to maintain administrative guidelines for each project. Now in work 10 projects and 2 more projects are considered. We can’t support 10 admin guides, especially if some of them are interrelated. We explore and look for the best way to a) attract participants, but also b) help them find a project for work.
There is another aspect - we want developers to write for developers, etc. The Book Sprint methodology revealed to me that the Process Manual worked because its authors perform these processes every day. I see the same thing in the security hardening guide; these guys breathe and live this topic.
Question: What keeps people from contributing to the documentation and from participating in it?
Answer: I think many people see that we use GitHub, Gerrit and XML and think, “Oh, this is not our specialty!” ... and move away. I introduced dozens of people who signed a member's license agreement (CLA). You have to be patient enough to go through this, since you are just writing documentation or you want to correct a typo, but you must go through the entire process of signing the CLA agreement. And I have the firm conviction that it is needed. I prefer the authors of documentation who participate in the OpenStack Foundation and the open source community, rather than random people.
And finally, the sheer volume of knowledge and hardware and hardware requirements can scare people away.
Q: What is the path to go from beginner to professional in terms of documentation in OpenStack?
Answer: There are a couple of possible paths. Be sure to try working with OpenStack, and then see which audience is yours. Then start by studying the documentation: “Does she answer my questions? Are there any missing fragments? ”And make sure that you try on the role of a user or developer when you read the document.
I think user groups are starting to do really cool things. Sean Roberts and Colin McNamara are leaders of the San Francisco Bay User Group, and they conduct a small workshop on how to write documentation, because there are people who want to master OpenStack, and one of the best ways to learn is to learn tools and documents. And a great way to learn is to record what you are doing.
We also have many groups of students who think something like, “I think the documentation is a good starting point.” For them, we have a list of tasks. See if there is any introductory information in the book. Perform a spell check. Check the text for capitalization rules, etc.
I also think that people can rate documents. Some people sent me a PDF with edits. And this is absolutely normal. Anything to start reading, evaluating, choosing what they can extract from this vast array of documentation, “Oh, this is where I can start.”
Question: Tell us about the camp for the preparation of authors of documentation?
Answer: Our training camp is a way to build connections between participants and encourage more people to participate in key documentation. We have it in Mountain View, California, on September 9 and 10.
We go through all the tools and processes so that everyone masters the tools sufficiently. For processes, we will answer questions like “Do I need to write a draft for this? Or is it just a mistake? How do I determine what to do? How do I choose a tool to check? What is a maven? When I add a new book, what should I do to publish it? How can I diagnose if I made a change, but I do not see it on the site? ”This is all on the first day.
And on the second day, this is more of a conversation, where we are talking about what you can work on. You do not have to go to work right that day, but many people say, “This is what we can actually do with the knowledge that we have now received.” On the second day, we eliminate documentation errors. The basic idea is that new members be immediately integrated into the core of documentation developers.
Question: What about translations?
Answer: The real value for me is, for example, that one day the OpenStack manual will be written in French, and instead of translating from English into French, there will be a reverse translation. I don’t think English should always be used as a source language. This is my personal opinion, but I don’t think that your first OpenStack manual is to have English manual.
Translation of documentation comes down to prioritization. The first priority for us is the translation of the process manual, since it is in greatest demand. Daisy, the translation coordinator, asked me last week what to translate next. And I answered: “To be honest, I would like to see this user guide translated, possibly after the Administrator’s Guide. We will try to reach the audience of operators and administrators in their language. ”
Question: Thank you for your time.
Answer: Thank you.
Source: https://habr.com/ru/post/190624/
All Articles