Second meeting Write the Docs Moscow. House Techwriters: do not forget that we exist
Although the second mite ’write Write the Docs Moscow took place a month ago, it’s never too late to publish a report and a summary of the reports. We managed to discuss almost everything: from documenting the RESTful API to professional toolpaths.
Mitap, by the way, brought together not only the “technical ghetto”, but also a wide range of other specialists who, in one way or another,experience pain with the documentation on the project: team leaders, analysts, testers, and even one technical director.
')
Our mitap was held on October 14 , Sunday (the top most popular questions about it included, “Why Sunday?”) In the office of IPONWEB. Mitapas Write the Docs run all over the world from Bangalore to San Francisco, from London to Seoul, the Russian branch of the community is only gaining activity, but there are already branches in Moscow, St. Petersburg and Novosibirsk.
Anton Thelin, Why and how we make video instructions
Video
Slides
Anton leads the technical documentation department of the SBIS company, which makes an electronic document management system. Why video? People do not want to read the instructions, they want to solve the problem. People want to be available and clearly explained.
Video is a convenient way to present a large amount of information, implement a script in dynamics, a sequence of actions. You can also focus the user's attention music or dubbing.
If the product is complex and it does not have a well thought-out interface, then without the visual part it is difficult to convey its essence to the user. The advantage is that it reduces the cost of technical support.
Cons - not suitable for all publication formats, it is difficult to embed in doc and pdf. It is difficult to search for it. High quality video to do more.
Another actual problem is the complexity of the update, but Anton's company solved this problem. They refused to record screencasts (screen capture) in favor of high-quality screenshots.
The company uses two video formats:
1. Video instruction is a sequence of actions, in detail and in steps. Duration ~ 2 minutes. 1 instruction is 1 problem. It does not tell about all the windows, check boxes, buttons. Then dubbing, background music, text explanations, captions are added.
2. An explanatory video. This is something at the junction of instructions and product presentations. A general idea without technical details solves several problems or scenarios. In this video can be people and animation. Duration 2-3 minutes.
Tools: Adobe Premiere and Adobe After Effect for editing, Adobe Audition for sound, Photoshop and Snagit for image editing. A project is being assembled from a variety of screenshots that are not relevant or erroneous and then easily replaced. Next, add the drawing of the mouse movement, animation, sound.
For the dubbing, they decided to use non-professional speakers, as they sounded too formal, so they use the voice of an employee of the company Ilya, who sings in the metalcore group. After the block of information, a 2 second pause for comprehension is given.
Videos are published both on your own hosting and on Youtube. A minus is blocking it by many companies for security reasons.
Of course, the VLSI collects all available statistics: the average viewing time, likes, calls to technical support, which were closed with the help of a link to the video.
Nikolai Volynkin, Technical Writer Version 2.0.1
Video
Slides
This is a repetition or better to say - an addition to the report from the SECR conference. Nikolai watched technical writers for a long time and noticed that they did not always know how to substantiate and measure their own benefits, and the leaders who set tasks for them also.
There are some related tasks that technical writers could solve. Nikolay told what kind of career trajectories and skill sets the technical staff has, how to sell your business new tasks to the business.
5 roles that can be performed by a technical writer:
1. Docops - devops for documentation, a writer / programmer, he is able to automate the generation, verification, unloading of documentation, trains the team to work with it and rebuilds all the processes around it.
Benefit - reduced manual labor, saving resources, feature delivery speed is higher.
2. UX-writer - a specialist in writing texts in interfaces.
Benefit - designers, companies, analysts or front-end developers do not always understand how to write correctly, how to communicate to the user functions, buttons, transitions. Texts are written on the principle of who first got up, order and sneakers. Convenience of the interface, reduction of time for technical support.
3. Technical evangelist , he talks about technology, interacts with the community, forms it.
Benefit - increasing trust and loyalty to the company, to the product, simplification of recruitment, HR brand.
4. Knowledge Manager - explores how a company produces, stores and transmits knowledge. Arranges these processes so that knowledge does not flow.
Benefits - reduction of bus factor, speed of adaptation of employees, both for beginners and for transitions inside, reuse of knowledge, reduction of risks.
5. Documentation Owner - PM and analyst for documentation. He builds the entire system of communication and user interaction in the documentation.
Benefit again in reducing support costs.
During the discussion, we recalled such a complex role as a content manager, which was not mentioned in the report.
Konstantin Valeev, Foliant
Video
Slides
Konstantin from Restrym told about the Foliant tool - the implementation of docops workflow based on the Markdown language. A year ago, as part of the mini-Hyperbaton in Yandex, Konstantin was already talking about Foliant, and since then, a lot has changed.
Documentation is written in MD files, and lying in different places, the tool supports continious integration, automatic assembly, it also allows you to expand MD to their liking.
Requirements: you need to give docx for customers and PDF with good typography, have human-readable sources (not XML).
A universal Pandoc converter is used under the hood, and the scripts in Python, bash are screwed on top. But over time, the number of scripts grew, so they were rewritten into a single, monolithic application.
The monolith was then made into a modular structure with the kernel managing the assembly, the preprocessors that convert MD for the work of the assemblers, and the assemblers themselves.
Foliant is essentially the glue between good tools (mkdoc, pandoc, slate, latex). Now they are trying to teach to consume sources of documentation from different formats.
In the project folder there is a config with the structure of the final document, styles and the actual MD files, then the preprocessors take the source MD files and apply processing to them to make the MD of the desired look in the style all.md (md in the foliant style), then collectors of the final documents ( pandoc, mkdoc) make them targues (documents). After building the MD, the linters are run, checking the syntax. Also sent email notifications of assemblies or errors.
All this can be collected in Docker, so that all packages can be delivered in one way, and not separately each.
Foliant supports advanced include, can pull code pieces from Gitlab / Github and pictures with layouts from Simpli, can draw diagrams, substitute parameters in the text, conditional statements.
Nikita Samokhvalov, Exhaustive documentation on the RESTful API
Video
Slides
Nikita Samokhvalov, Technical Director of Notamedia, told how they set up the generation of API documentation based on Open API 3.0.
Like everyone, they started with Google Docs, but it doesn’t have any versioning or the ability to create branches. Then they began to simply write MD files in the repository, the problem of versioning and creating branches was solved, but everything was slow. Then came to autogeneration.
There were the following requirements for documentation: inheritance and reuse of pieces of documentation, the ability to provide a link to descriptions of parameters and methods, information on the differentiation of access rights, documentation as a code (synchronous deployments and changes). In addition, the documentation is not laid out publicly, only for its team and the team of development personnel.
Chose the format OpenAPI 3.0. Why? It is the freshest, it supports more opportunities, although there is still a small ecosystem and expertise around it.
They took the shins tool (shows MD files in a beautiful landing page with examples of requests, description of methods, parameters), widdershins (converter from yaml / json to MD), also they wrote their own specker package (installs all the necessary dependencies, works through npm, also checks correct file allocation structure).
The installation of the environment and the assembly of the documentation are done in one line in the console. The dependencies / folder contains files that need to be reused in each project, for example, a description of authorization.
Nikita also spoke about how they work with branches in a distributed team, when the task is to update the documentation and, of course, about the pitfalls and difficulties that accompanied the introduction of OpenAPI 3.0.
Svetlana Novikova, Knowledge Management with the Competency Matrix
Video
Slides
Svetlana (this is me, by the way) described how they in the company reloaded the tool from the personnel management sphere as a matrix of competencies, what is the use of knowledge management, how does the tool help to reduce bus factor, it’s better to start newbies, even find parts of the code for refactoring.
Danila Medvedev, NeuroCode
Video
Danila told about not yet understandable to everyone and, perhaps, ahead of our time, a tool for modeling and storing knowledge called NeuroCode.
This tool is useful to anyone involved in the design of IT systems. In particular, Danila offers to abandon document-centric systems. Any system is considered as a network, through the nodes of which some information is transmitted. This principle is subject to all elements of the system - push updates, the transfer of documents, the transfer of feedback. The goal of the NeuroCode is to “reduce the overhead on supporting processes and enhance the collective intelligence of the organization”.
The NeuroCode project grew out of solving a problem - how to create a good information repository for a team or for oneself, how to create a model of information. The prototype of the system is made and works, it is being tested with the help of system engineers and business architects. The system has a scalable interface and it is based on a fractal data structure. It is also based on the ideas of Douglas Engelbart (this is one of the first researchers of human-machine interface, the author of the concepts of GUI, hypertext, etc.) of the 1960s about Open Hyper-Document Systems (OHS), when the system is not document-centric, but one , that is, it implements all the processes of human activity.
PS In general, look at the video better.
The next write session, Write the Docs Moscow, will take place on December 7 at the office of Positive Technologies, and will be held in the format of Positive Authoring Tools Battle.
Mitap, by the way, brought together not only the “technical ghetto”, but also a wide range of other specialists who, in one way or another,
')
Our mitap was held on October 14 , Sunday (the top most popular questions about it included, “Why Sunday?”) In the office of IPONWEB. Mitapas Write the Docs run all over the world from Bangalore to San Francisco, from London to Seoul, the Russian branch of the community is only gaining activity, but there are already branches in Moscow, St. Petersburg and Novosibirsk.
Anton Thelin, Why and how we make video instructions
Video
Slides
Anton leads the technical documentation department of the SBIS company, which makes an electronic document management system. Why video? People do not want to read the instructions, they want to solve the problem. People want to be available and clearly explained.
Video is a convenient way to present a large amount of information, implement a script in dynamics, a sequence of actions. You can also focus the user's attention music or dubbing.
If the product is complex and it does not have a well thought-out interface, then without the visual part it is difficult to convey its essence to the user. The advantage is that it reduces the cost of technical support.
Cons - not suitable for all publication formats, it is difficult to embed in doc and pdf. It is difficult to search for it. High quality video to do more.
Another actual problem is the complexity of the update, but Anton's company solved this problem. They refused to record screencasts (screen capture) in favor of high-quality screenshots.
The company uses two video formats:
1. Video instruction is a sequence of actions, in detail and in steps. Duration ~ 2 minutes. 1 instruction is 1 problem. It does not tell about all the windows, check boxes, buttons. Then dubbing, background music, text explanations, captions are added.
2. An explanatory video. This is something at the junction of instructions and product presentations. A general idea without technical details solves several problems or scenarios. In this video can be people and animation. Duration 2-3 minutes.
Tools: Adobe Premiere and Adobe After Effect for editing, Adobe Audition for sound, Photoshop and Snagit for image editing. A project is being assembled from a variety of screenshots that are not relevant or erroneous and then easily replaced. Next, add the drawing of the mouse movement, animation, sound.
For the dubbing, they decided to use non-professional speakers, as they sounded too formal, so they use the voice of an employee of the company Ilya, who sings in the metalcore group. After the block of information, a 2 second pause for comprehension is given.
Videos are published both on your own hosting and on Youtube. A minus is blocking it by many companies for security reasons.
Of course, the VLSI collects all available statistics: the average viewing time, likes, calls to technical support, which were closed with the help of a link to the video.
Nikolai Volynkin, Technical Writer Version 2.0.1
Video
Slides
This is a repetition or better to say - an addition to the report from the SECR conference. Nikolai watched technical writers for a long time and noticed that they did not always know how to substantiate and measure their own benefits, and the leaders who set tasks for them also.
There are some related tasks that technical writers could solve. Nikolay told what kind of career trajectories and skill sets the technical staff has, how to sell your business new tasks to the business.
5 roles that can be performed by a technical writer:
1. Docops - devops for documentation, a writer / programmer, he is able to automate the generation, verification, unloading of documentation, trains the team to work with it and rebuilds all the processes around it.
Benefit - reduced manual labor, saving resources, feature delivery speed is higher.
2. UX-writer - a specialist in writing texts in interfaces.
Benefit - designers, companies, analysts or front-end developers do not always understand how to write correctly, how to communicate to the user functions, buttons, transitions. Texts are written on the principle of who first got up, order and sneakers. Convenience of the interface, reduction of time for technical support.
3. Technical evangelist , he talks about technology, interacts with the community, forms it.
Benefit - increasing trust and loyalty to the company, to the product, simplification of recruitment, HR brand.
4. Knowledge Manager - explores how a company produces, stores and transmits knowledge. Arranges these processes so that knowledge does not flow.
Benefits - reduction of bus factor, speed of adaptation of employees, both for beginners and for transitions inside, reuse of knowledge, reduction of risks.
5. Documentation Owner - PM and analyst for documentation. He builds the entire system of communication and user interaction in the documentation.
Benefit again in reducing support costs.
During the discussion, we recalled such a complex role as a content manager, which was not mentioned in the report.
Konstantin Valeev, Foliant
Video
Slides
Konstantin from Restrym told about the Foliant tool - the implementation of docops workflow based on the Markdown language. A year ago, as part of the mini-Hyperbaton in Yandex, Konstantin was already talking about Foliant, and since then, a lot has changed.
Documentation is written in MD files, and lying in different places, the tool supports continious integration, automatic assembly, it also allows you to expand MD to their liking.
Requirements: you need to give docx for customers and PDF with good typography, have human-readable sources (not XML).
A universal Pandoc converter is used under the hood, and the scripts in Python, bash are screwed on top. But over time, the number of scripts grew, so they were rewritten into a single, monolithic application.
The monolith was then made into a modular structure with the kernel managing the assembly, the preprocessors that convert MD for the work of the assemblers, and the assemblers themselves.
Foliant is essentially the glue between good tools (mkdoc, pandoc, slate, latex). Now they are trying to teach to consume sources of documentation from different formats.
In the project folder there is a config with the structure of the final document, styles and the actual MD files, then the preprocessors take the source MD files and apply processing to them to make the MD of the desired look in the style all.md (md in the foliant style), then collectors of the final documents ( pandoc, mkdoc) make them targues (documents). After building the MD, the linters are run, checking the syntax. Also sent email notifications of assemblies or errors.
All this can be collected in Docker, so that all packages can be delivered in one way, and not separately each.
Foliant supports advanced include, can pull code pieces from Gitlab / Github and pictures with layouts from Simpli, can draw diagrams, substitute parameters in the text, conditional statements.
Nikita Samokhvalov, Exhaustive documentation on the RESTful API
Video
Slides
Nikita Samokhvalov, Technical Director of Notamedia, told how they set up the generation of API documentation based on Open API 3.0.
Like everyone, they started with Google Docs, but it doesn’t have any versioning or the ability to create branches. Then they began to simply write MD files in the repository, the problem of versioning and creating branches was solved, but everything was slow. Then came to autogeneration.
There were the following requirements for documentation: inheritance and reuse of pieces of documentation, the ability to provide a link to descriptions of parameters and methods, information on the differentiation of access rights, documentation as a code (synchronous deployments and changes). In addition, the documentation is not laid out publicly, only for its team and the team of development personnel.
Chose the format OpenAPI 3.0. Why? It is the freshest, it supports more opportunities, although there is still a small ecosystem and expertise around it.
They took the shins tool (shows MD files in a beautiful landing page with examples of requests, description of methods, parameters), widdershins (converter from yaml / json to MD), also they wrote their own specker package (installs all the necessary dependencies, works through npm, also checks correct file allocation structure).
The installation of the environment and the assembly of the documentation are done in one line in the console. The dependencies / folder contains files that need to be reused in each project, for example, a description of authorization.
Nikita also spoke about how they work with branches in a distributed team, when the task is to update the documentation and, of course, about the pitfalls and difficulties that accompanied the introduction of OpenAPI 3.0.
Svetlana Novikova, Knowledge Management with the Competency Matrix
Video
Slides
Svetlana (this is me, by the way) described how they in the company reloaded the tool from the personnel management sphere as a matrix of competencies, what is the use of knowledge management, how does the tool help to reduce bus factor, it’s better to start newbies, even find parts of the code for refactoring.
Danila Medvedev, NeuroCode
Video
Danila told about not yet understandable to everyone and, perhaps, ahead of our time, a tool for modeling and storing knowledge called NeuroCode.
This tool is useful to anyone involved in the design of IT systems. In particular, Danila offers to abandon document-centric systems. Any system is considered as a network, through the nodes of which some information is transmitted. This principle is subject to all elements of the system - push updates, the transfer of documents, the transfer of feedback. The goal of the NeuroCode is to “reduce the overhead on supporting processes and enhance the collective intelligence of the organization”.
The NeuroCode project grew out of solving a problem - how to create a good information repository for a team or for oneself, how to create a model of information. The prototype of the system is made and works, it is being tested with the help of system engineers and business architects. The system has a scalable interface and it is based on a fractal data structure. It is also based on the ideas of Douglas Engelbart (this is one of the first researchers of human-machine interface, the author of the concepts of GUI, hypertext, etc.) of the 1960s about Open Hyper-Document Systems (OHS), when the system is not document-centric, but one , that is, it implements all the processes of human activity.
PS In general, look at the video better.
The next write session, Write the Docs Moscow, will take place on December 7 at the office of Positive Technologies, and will be held in the format of Positive Authoring Tools Battle.
Source: https://habr.com/ru/post/431210/
All Articles