Second meeting Write the Docs Moscow. House Techwriters: do not forget that we exist
Although the second à la carte Write the Docs Moscow took place a month ago, it’s never too late to publish a report and a brief summary of reports. We managed to discuss almost everything: from documenting the RESTful API to professional toolpaths.
Mitap, by the way, gathered 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 leads, analysts, testers, and even one technical director.
Our mitap was held on October 14 , Sunday (the top most popular questions about him 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 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 manages the technical documentation department of the VLSI 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 look 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 their 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 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 do 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.
There are 5 roles that a technical writer can perform:
1. Docops - devops for documentation, a writer / programmer, he can automate the generation, testing, uploading of documentation, trains the team to work with it and rearranges 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 functions, buttons, transitions to the user. 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 transfers 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 the content manager, which was not noted in the report.
Konstantin Valeev, Foliant
Video
Slides
Konstantin from Restrim talked about the Foliant tool- implementation of docops workflow based on 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 source code (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.
The project folder contains the 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 configured the generation of API documentation based on Open API 3.0.
Like everyone, they started with Google Docs, but it has neither versioning nor 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 OpenAPI 3.0 specification. 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, a description of methods, parameters), widdershins (a converter from yaml / json to MD), also they wrote their own specker package(installs all necessary dependencies, works through npm, also checks the correctness of the 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) told how they in the company reloaded the tool from the personnel management sphere, how the competence matrix is, what is the use of knowledge management, how the tool helps to reduce the bus factor, it’s better to start a newbie, even find parts 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 purpose of the NeuroCode work is “to reduce the overhead on supporting processes and to strengthen 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 now 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 a document-centric, but one , that is, it implements all the processes of human activity.
PS In general, look at the video better.
Next mita Write the Docs MoscowIt will be held 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, gathered 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 him 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 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 manages the technical documentation department of the VLSI 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 look 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 their 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 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 do 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.
There are 5 roles that a technical writer can perform:
1. Docops - devops for documentation, a writer / programmer, he can automate the generation, testing, uploading of documentation, trains the team to work with it and rearranges 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 functions, buttons, transitions to the user. 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 transfers 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 the content manager, which was not noted in the report.
Konstantin Valeev, Foliant
Video
Slides
Konstantin from Restrim talked about the Foliant tool- implementation of docops workflow based on 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 source code (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.
The project folder contains the 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 configured the generation of API documentation based on Open API 3.0.
Like everyone, they started with Google Docs, but it has neither versioning nor 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 OpenAPI 3.0 specification. 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, a description of methods, parameters), widdershins (a converter from yaml / json to MD), also they wrote their own specker package(installs all necessary dependencies, works through npm, also checks the correctness of the 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) told how they in the company reloaded the tool from the personnel management sphere, how the competence matrix is, what is the use of knowledge management, how the tool helps to reduce the bus factor, it’s better to start a newbie, even find parts 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 purpose of the NeuroCode work is “to reduce the overhead on supporting processes and to strengthen 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 now 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 a document-centric, but one , that is, it implements all the processes of human activity.
PS In general, look at the video better.
Next mita Write the Docs MoscowIt will be held on December 7 at the office of Positive Technologies, and will be held in the format of Positive Authoring Tools Battle.