2番目のMitapは、ドキュメントモスクワを書きます。 House Techwriters：私たちが存在することを忘れないでください

Write the Docs Moscowの2回目の会議は1か月前に開催されましたが、レポートとレポートの要約を公開するのに遅すぎることはありません。 RESTful APIの文書化から、技術ライターの専門的な軌跡まで、事実上すべてをうまく議論できました。



ちなみに、Mitapは「技術的なゲットー」だけでなく、チームリーダー、アナリスト、テスター、さらには1人のテクニカルディレクターなど、何らかの形でプロジェクトのドキュメントを扱うさまざまな専門家を集めました。









私たちの会議は 、日曜日の10月14日に開催されました（彼は彼に関する最も人気のある質問のトップ、「なぜ日曜日ですか？」）IPONWEBオフィスで開催されました。 Write the Docsラリーは、バンガロールからサンフランシスコ、ロンドンからソウルまで世界中で開催されています。ロシアのコミュニティ支部は活動を増やしているだけですが、モスクワ、サンクトペテルブルク、ノボシビルスクにはすでに支部があります。



アントン・テリン、ビデオ命令を行う理由と方法

映像

スライド



アントンは、電子文書管理システムを構築するVLSIの技術文書部門を管理しています。 なぜビデオなのか？ 人々は指示を読みたくない、問題を解決したい。 人々は、アクセスしやすく、明確になりたいと思っています。



ビデオは、大量の情報を提示し、ダイナミクス、アクションのシーケンスでスクリプトを実装するための便利な方法です。 音楽やダビングでユーザーの注意を引き付けることもできます。



製品が複雑で、よく考えられたインターフェイスがない場合、視覚的な部分がなければ、その本質をユーザーに伝えることは困難です。 プラスは、テクニカルサポートコストを削減できることです。



短所-すべての出版形式に適しているわけではありません。docやpdfに埋め込むことは困難です。 検索するのは難しいです。 高品質のビデオはより高価です。



別の緊急の問題はアップデートの複雑さですが、アントンのキャンペーンはこの問題を解決しました。 高品質のスクリーンショットを優先して、スクリーンキャスト（スクリーンキャプチャ）の記録を拒否しました。



同社は2つのビデオ形式を使用しています。

1.ビデオ命令は、一連のアクションであり、詳細かつ段階的です。 所要時間〜2分。 1つの命令は1つの問題です。 すべてのウィンドウ、ジャックダウ、ボタンについては説明していません。 その後、ダビング、BGM、テキストの説明、キャプションを追加しました。



2.説明ビデオ。 これは、製品の説明とプレゼンテーションの接点です。 技術的な詳細のない一般的なビューは、いくつかの問題やシナリオを解決します。 このビデオには、人物とアニメーションが含まれる場合があります。 所要時間は2〜3分です。



ツール：編集にはAdobe PremiereおよびAdobe After Effect、音声にはAdobe Audition、画像の編集にはPhotoshopおよびSnagit。 このプロジェクトはさまざまなスクリーンショットから組み立てられますが、これらは関連性がなく、エラーでもないため、簡単に置き換えることができます。 次に、マウスの動き、アニメーション、サウンドを描画します。



彼らはあまりにもフォーマルに聞こえたので、ダビングにプロではないアナウンサーを使用することを決めたので、彼らはメタルコアグループで歌う会社の従業員イリヤの声を使用します。 情報のブロックの後、反射のための2秒の休止が必然的に与えられます。



ビデオは、独自のホスティングとYoutubeの両方で公開されています。 欠点は、セキュリティ上の理由から多くの企業によってブロックされていることです。



もちろん、VLSIは利用可能なすべての統計を収集します：平均視聴時間、いいね！、ビデオリンクを使用して閉じられたテクニカルサポートコール。



Nikolay Volynkin、テクニカルライターバージョン2.0.1

映像

スライド



これは、繰り返しであり、むしろ、SECR会議からの報告を補足するものです。 ニコライは長い間テクニカルライターを見て、彼らが自分の利益を正当化して測定する方法と、タスクを設定するリーダーを常に知っているわけではないことに気付きました。



テクニカルライターが解決できる関連タスクがいくつかあります。 ニコライは、キャリアの軌跡とスキルセットには技術的な説明があり、新しいタスクをビジネスに販売する方法を説明しました。



テクニカルライターが果たすことができる5つの役割：

1. Docops-ドキュメンテーション、ライター/プログラマーのdevops。ドキュメントの生成、検証、アップロードを自動化する方法を知っており、チームがそれを使用するようにトレーニングし、その周辺のすべてのプロセスを再構築します。



利点は、手作業の削減、リソースの節約、および機能の提供速度の向上です。



2. UXライター -インターフェイスでのテキスト作成のスペシャリスト。



利点-デザイナー、詩人、アナリスト、またはフロントエンドの開発者は、正しく書く方法、機能、ボタン、遷移をユーザーに伝える方法を常に理解しているわけではありません。 テキストは、最初に起きた人とスリッパの原則に従って書かれています。 インターフェイスの利便性、テクニカルサポートの時間短縮。



3. 技術的な伝道者 、彼は技術について語り、コミュニティと対話し、それを形作ります。



利点-会社、製品、雇用の簡素化、HRブランドに対する信頼と忠誠心の向上。



4. ナレッジマネージャー -企業がナレッジを生成、保存、および転送する方法を調査します。 知識が流出しないようにこれらのプロセスを確立します。



利点-バスファクターの削減、従業員の適応速度、初心者および移行中の両方、知識の再利用、リスク削減。



5. ドキュメント所有者 -PMおよびドキュメントアナリスト。 彼は、ドキュメント内のコミュニケーションとユーザーインタラクションのシステム全体を構築します。



メリットは、サポートコストを削減することです。



議論の中で、コンテンツマネージャーとしてのそのような統合された役割を思い出しましたが、これはレポートには記載されていません。



コンスタンチン・バレエフ、葉

映像

スライド



RestrimのConstantineが、 Foliantツール-Markdown言語に基づいたdocopsワークフローの実装について話しました。 1年前、 YandexのミニHyperbatonの一環として、コンスタンチンはすでにFoliantについて話していましたが、それ以来多くのことが変わりました。



ドキュメントはMDファイルで記述されており、さまざまな場所にあり、ツールは継続的な統合、自動アセンブリをサポートし、MDを好みに合わせて拡張することもできます。



要件：お客様にdocxを提供し、適切なタイポグラフィを備えたPDFを提供し、人間が読めるソース（XMLではない）を用意する必要があります。



内部では、汎用のPandocコンバーターが使用され、Python、bashスクリプトが上に巻かれています。 しかし、時間の経過とともにスクリプトの数が増えたため、スクリプトは単一のモノリシックアプリケーションに書き換えられました。



次に、モノリスから、アセンブリを制御するカーネル、アセンブラーの作業用にMDを変換するプリプロセッサー、およびアセンブラー自身でモジュール構造を作成しました。



Foliantは基本的に、優れたツール（mkdoc、pandoc、slate、latex）間の接着剤です。 現在、彼らはさまざまな形式のドキュメントソースを使用する方法を教えようとしています。



プロジェクトフォルダーには、最終ドキュメントの構造、スタイル、MDファイル自体の構成があり、プリプロセッサーがソースMDファイルを取得し、それらに処理​​を適用して、all.mdのスタイル（希望するスタイルのmd）で目的のMDを作成し、最終ドキュメントのコレクター（ pandoc、mkdoc）はそれらをターゲット（ドキュメント）にします。 MDを組み立てた後、リンターを実行して構文を確認します。 ビルドまたはバグに関するビルド通知も送信されます。



これらはすべてDockerで収集できるため、すべてのパッケージは個別にではなく、1つの方法で配信されます。



Foliantは高度なインクルードをサポートし、Gitlab / Githubからコードの一部を抽出し、Simpliのレイアウトで画像を抽出し、ダイアグラムを描画し、テキストのパラメーターを置換し、条件ステートメントを作成できます。







Nikita Samokhvalov、RESTful APIに関する包括的なドキュメント

映像

スライド



NotamediaのテクニカルディレクターであるNikita Samokhvalovは、Open API 3.0に基づいてAPIドキュメントの生成をどのように構成したかを語りました。



他の皆と同じように、彼らはGoogleドキュメントから始めましたが、バージョン管理もブランチを作成する機能もありません。 その後、リポジトリにMDファイルを書き始めたばかりで、バージョン管理とブランチ作成の問題は解決しましたが、すべてが遅かったです。 その後、自動生成になりました。



ドキュメントには、ドキュメントの継承と再利用、パラメーターとメソッドの説明へのリンクを提供する機能、アクセス権の区別に関する情報、コードとしてのドキュメント（同期展開と変更）の要件がありました。 また、ドキュメントは公開されておらず、チームと卒業生開発チームのみが対象です。



OpenAPI 3.0仕様を選択しました。 なんで？ 新鮮で、より多くの機能をサポートしていますが、まだ小さなエコシステムと専門知識があります。



彼らはshinsツール（リクエストの例、メソッドの説明、パラメーターを含む美しいランディングページにMDファイルを表示）、 widdershins （yaml / jsonからMDコンバーターへ）、独自のspeckerパッケージを作成しました（すべての必要な依存関係をインストールし、npmで動作し、チェックもします）ファイル割り当て構造の正確さ）。



環境のセットアップとドキュメントの組み立ては、コンソールの1行で行います。 承認の説明など、各プロジェクトで再利用する必要があるファイルは、依存関係/フォルダーに分類されます。



Nikitaは、ドキュメントを更新することがタスクである場合、分散チームのブランチでどのように機能するか、そしてもちろん、OpenAPI 3.0の実装に伴う落とし穴と問題点についても話しました。



Svetlana Novikova、コンピテンシーマトリックスを使用したナレッジマネジメント

映像

スライド



スベトラーナ（ちなみに、これは私です）が、社内の人事管理領域からエンドツーエンドの機器のリブートをコンピテンシーマトリックスとしてどのように手配したか、この方法でのナレッジマネジメントの使用方法、バスファクターを減らすために機器がどのように役立つか、新人に乗る、部品を見つけるのが良いかについて話しましたリファクタリング用のコード。



ダニラ・メドベージェフ、NeuroCode

映像



ダニラは、誰もが理解できるツールについて、そしておそらく私たちの時代に先駆けて、ニューロコードと呼ばれる知識をモデル化して保存するためのツールについて語った。



このツールは、ITシステムの設計に関わるすべての人に役立ちます。 特に、Danilaはドキュメントベースのシステムを放棄することを提案しています。 何らかの情報が送信されるノードに応じて、どのシステムもネットワークと見なされます。 システムのすべての要素がこの原則に従います-プッシュ更新、ドキュメント転送、フィードバック転送。 NeuroCodeの目的は、「プロセスをサポートするための非生産的なコストを削減し、組織の集合知能を強化すること」です。



NeuroCodeプロジェクトは、問題を解決することから生まれました。チームまたは自分のために情報の良いリポジトリを作成する方法、情報のモデルを作成する方法です。 システムのプロトタイプが作成され、動作します。現在、システムエンジニアとビジネスアーキテクトの助けを借りてテストされています。 このシステムにはスケーラブルなインターフェースがあり、フラクタルデータ構造に基づいています。 また、システムがドキュメントベースではなく、単一のオープンハイパードキュメントシステム（OHS）についての1960年代のダグラスエンゲルバート（これは、ヒューマンマシンインターフェイスに関する最初の研究者の1人であり、GUI、ハイパーテキストなどの概念の著者）のアイデアにも基づいています、つまり、人間の活動のすべてのプロセスを実装します。



PS一般に、ビデオをよく見ましょう。



Write the Docs Moscowの次の会議は、12月7日にPositive Technologiesのオフィスで開催され、Positive Authoring Tools Battleの形式で開催されます。