マークダウンir ヤンデックス講義

ドキュメントを開発するとき、標準だけでなく、その使用の利便性にもガイドされます。 標準はドキュメントの構成と形式を決定し、形式は利便性に基づいて構築されます。 開発者のSergey Bocharovは、Markdownドキュメントのパスと、このフォーマットの使いやすさと引き換えに解決しなければならない問題について語っています。

役に立たないという印象を受けることもありますが、この形式には役立っています。 したがって、マークダウンir。

-私たちは今何がスケールにあるかを知っています
そして今何が起こっているのか。
勇気の時が私たちの時計に当たりました。
そして勇気は私たちを去りません。

死んだ弾丸の下に横たわるのは怖くない、
ひどくホームレスのままにしないでください。
そして、ロシアのスピーチ、あなたを救います
偉大なロシア語。

私たちはあなたを自由で純粋に運びます
両方の孫を与えて捕虜から救います-
永遠に。

こんばんは、友達、私の名前はセルゲイ・ボチャロフです。 私はアンナ・アフマトヴァの詩「勇気」から始めました。 大祖国戦争中の1942年に書かれましたが、それでも詩人たちは、戦争の長年にわたって浪費され、実際に踏みにじられた精神的な富を返すよりも、爆撃によって破壊された工場を復元して建設する方がはるかに簡単であることを理解していました。

詩は、美しいと感じることを学ぶのに役立つ数少ない手段の1つです。 今日私たちは技術文書について話している-そんな遠い分野は詩とは違うように思えますが、特にこの形式で作業するときは、美しいスタイルを維持し、単一のスタイルを維持することが非常に重要です。 Markdownは、オープンソースの世界で技術文書を作成するための事実上の標準となっています。 そして、さまざまな専門分野の人々を団結させました。

私には困難であると同時に楽しい使命があります。 YandexでMarkdownのドキュメントを組み立てる気持ちを十分に持たせ、また開発したツールを共有してほしい。 あなたもあなたのプロジェクトでそれらを使うことを望みます。

YandexのJavaScriptが大好きなので、開発されたツールはJSで書かれています。 そして、すべての開発はこの言語を中心に行われます。 別の開発環境や誇大広告Reactがある場合、動揺する必要はありません-GitHubで類似物を見つけることができると思います。

おそらく多くの人が疑問に思っているのに、なぜMarkdownはサーになったのでしょうか？ これは比metaであり、Yandexのプロセスをロボット化しようとするという事実に関連しています。

Markdownは、多数のツールも開発しています。 現在までに、私たちはすでに多くのツールを開発しており、開発を続けています。 役に立たないという印象を受けることもありますが、この形式には役立っています。 したがって、マークダウンir。



最初のグローバルパートでは、なぜこの形式で書いているのか、なぜそのためのツールを開発しているのかについてお話します。 第二部では、コンテンツの品質を維持する方法、翻訳方法、多くのリポジトリから1つのサイトを構築する方法について、ライブラリの例について詳しく説明します。

Markdownは、2004年にJohn GruberとAaron Schwartzによって作成されました。 その考えは、単純なテキスト構文を使用して、それをよりリッチでより有効なHTMLに変換することでした。



テキストの第1レベル、第2レベル、およびいくつかの段落の見出しがあります。

豊富なツールを備えたDITAがあるのに、なぜ新しいフォーマットが必要なのですか？ Markdown用の新しいツールを作成する理由 一緒に答えてみましょう。



DITAの構文はより複雑であり、それと連携する特定の開発環境を用意することをお勧めします。 これがXML形式であることは明らかであり、テキストエディターでも開きます。 ただし、SVGも開きますが、誰もそこに描画しません。誰もがPhotoshopまたはSketchを使用します。

それどころか、Markdownはより軽い構文を持っているため、多くの開発者がMarkdownをとても気に入っています。 その結果、Markdownのドキュメントは、寄稿者と開発者が積極的に参加するテクニカルライターによって作成および保守され、DITAのドキュメントは多くの場合、テクニカルライターによってのみ開発されます。開発者と寄稿者は積極的に参加しません。

Markdownのドキュメントを含むサイトの鮮やかな例はnpmサイトです。今日では475千のモジュールが含まれており、毎日ますます増えています。


最も人気のあるものを次に示します。 Gulpなどの誰かのサイトにアクセスしてドキュメントセクションに移動すると、すぐにGitHubに移動します。そこで、gulp.js APIがMarkdownで説明されていることがわかります。



したがって、何らかの理由でMarkdownをまだ使用していない場合、またはバイパスする場合は、使用して開発者を満足させてください。

スタイルと構文。 最高機密であるレゴの内部ライブラリの例を検討することを提案します。 次に、デモを行います。



意外とそうですか？ これらのブロックはすべて異なります。 ロゴブロック、ティーザーなどがあります。これらは、事実上の標準であるGitHubに保存されています。

ここにはライブラリの一般的な説明があり、ブロックディレクトリもあります。各ディレクトリにはこのブロックの説明があります。 ドキュメントはコードの一部と見なされるため、適切な名前でドキュメントを呼び出します。 交換、検索、交換の場合にも便利です。 むかしむかし、テクニカルライターが各ドキュメントに取り組みました。 翻訳者は英語版にも取り組みました。理想的には、ドキュメント、ロシア語版、英語版は一貫している必要があります。つまり、構造と内容は同じである必要があります。

ドキュメントは開発者自身によっても積極的に開発されており、多くのドキュメントがあります。 社内で構築しようとしているプロセスは次のとおりです。新しい機能または新しいブロックを開発した開発者は、プールリクエストまたは問題の形式でテクニカルライターのタスクを設定します。

テクニカルライターがこの機能を説明し、言語バージョンのドキュメントが必要な場合は翻訳を断念します。 そして誰もが幸せですが、それは完璧な世界です。 しかし、現実の世界では、状況はしばしば次のとおりです。開発者自身が来て、ドキュメントを修正します。

ここで、最初の問題-一貫性の喪失に直面しています。 次の問題は、ドキュメントを書くスタイルを変えることでもあります。

思われる-主なことは、機能が記述されていることです。 わかった、いや。 ドキュメントがテクニカルライターによって書かれた後、開発者は喜んでいました。

そして、数十人の開発者がコミットしてそこに来たとき、彼らはすでに動揺し、最終的には泣き出しました。 彼らは言う-あなたは文書を書き直す必要があり、それは理解できなくなり、読むことは不可能であり、多くの異なる理解できない構造、ニンジン、問題のあるテキストのマーカーがあります。

それらを使用すると、どういうわけか戦うことができる必要があります。 テクニカルライターはそれらを知っており、対処することができます。開発者はドキュメントでそれらを許可することが多く、そのようなドキュメントは読むのが不快です。

たとえば、誰もがここで快適ですか？ 誰もがそれが何であるかを理解していますか？ 明らかにこれはgitについてであり、これはドキュメントに記載されています。 より理解しやすいオプションを次に示します。

GitHubの経験がほとんどない開発者は、開発の達人によって書かれたドキュメントを読むときに困難を感じることがあります。 したがって、次の問題を追加します-スタイルと用語の保存。 開発者は多くのことをコミットし、テクニカルライターはほとんど見えません。スタイルの統一性は壊れています。



このアプローチの次の問題は、構文が壊れていることです。 Markdownを使用すると、まったく異なる方法で記述し、同じ結果を得ることができます。 各ケースの技術文書の開発者は、見出し、リストの作成、スクリーンショットの挿入などについて合意しています。

実際、現実はしばしば望まれるものとは異なり、この問題に対処できなければなりません。 結果は期待されているように見えますが、この問題が現在解決されていない場合は、アセンブリ段階で解決する必要があります。 多くの場合、タスクがあります-たとえば、第3レベルのすべての見出しを見つけるには bektikamiと2ピクセル増加します。 ライニング段階で解決しない場合は 、アセンブリ段階で解決し、大きなスクリプトを作成する必要があります。

したがって、次の問題-Markdown構文を追加します。 苦労している3つの主な課題がありました。 また、オープンソースプロジェクト、特にBEMもあります。 開発者、テクニカルライター、翻訳者に加えて、オープンソースプロジェクトにも貢献者がいます。 貢献者は、製品の改善を支援し、感謝しています。 たくさんあります。 彼らは私たちにプールリクエストを送信し、質の高いコンテンツを彼らと共有します。 そのため、何らかの方法でソリューションを探す必要があります。

次のセクションでは、自動テスト、リンティングについて説明します。 Markdown構文を一貫してチェックし、文法エラーや問題のテキストのマーカーを見つける方法をどうにかして学ぶためにできること。 これは私のお気に入りのセクションです。 リンティングの進歩は、テクニカルライターの進歩に役立つと思います。

remark-lintというツールから始めましょう。 構文と記述スタイルを確認できます。 発言自体はパブリックドメインであり、私たちによって開発されたものではなく、使用しています。独自のルールセットがあり、50以上あります。これらのルールに加えて、独自のルールを作成し、ガイドを発言に含めました。



どのように機能しますか？ コンテンツを含むテストファイルがあり、第1レベル、第2レベル、およびいくつかのリストの見出しがあるとします。



ターミナルでコマンドを入力します。 これは、処理中のチームです。 テクニカルライターがGitHubでコミットし、ドキュメントが正常な状態である場合、エラーがないことを示すメッセージが表示されます。 そして、コミットはGitHubに送られます。 エラーがあるとします-たとえば、最初の見出しの2番目のレベルにし、2番目の見出しに「Hello」と感嘆符を追加します。 同じコマンドを実行すると、3つのエラーが発生します。



リンティングの進行は、テクニカルライターの進行に影響します。 テクニカルライターは、見出し、規則に感嘆符を付けないことに同意したことを思い出します。すべて順調です。 これらのルールはどのように関係していますか？ プロジェクトのルートにあるremarkrcファイルには、独自のルールのセット（私はそれらを削減しました）と、コメント自体の借用ルールのセットを定義します。

次のツールはyaspellerです。 ドキュメントの文法とスペルミスをチェックします。 ドキュメントはYandex.Technologiesにあります -ところで、それはgitで書かれています。 あなたはそれを読むことができます、すべてが同じ原則に従ってそこで動作します：スペルミスがあります-メッセージが表示されます。 貢献者、あなたをプールリクエストしようとしている開発者は、いくつかの修正を送信しますが、スペルダウンやMarkdown構文の不正確さでそれらを送信することはできません。 したがって、これらのツールは接続するのに非常に便利であり、prekommitで機能します。

次のセクションは翻訳についてです。 md2xliffツールを開発しました。 私たちは多くのオープンソース文書と少しの内部文書を翻訳します。 オープンソースドキュメントの場合、プールリクエストを送信する寄稿者がいます。送信しやすくするために、GitHubインターフェースまたは散文サービスを使用してリンクをたどることを提供するWebサイトでサイコロを作成します。 io。 たとえば、彼らが入り、変更を加え、[OK]をクリックすると、プールリクエストが到着します。

これをすべてサポートする方法は？ 文書がテクニカルライターによって作成され、翻訳者が翻訳し、ユーザーが来て-最初はロシア語版で-そこに何かを修正したとします。 英語版をどうしますか？ そこで何かを編集する必要がありますか？ 明確ではありません。 修正されたタイプミスを探す方法も不明です。 または、GitHubに移動して、差分の違いを確認できます。 しかし、これはまだタスクです。翻訳者に任せる必要があります。 解決策を見つける必要があります。

2番目の状況があります。 たとえば、開発者はライブラリの2番目のバージョンを作成し、ドキュメント全体を取得せず、30ページを書き換えなかった後、その部分を削除して追加しました。 そして削除された場合-それは何をすべきかが明確ではありません。 GitHubの差分でこれを確認する必要があります。

になる方法 これは、逃げ道のない難しい状況のようです。 しかし、あなたが翻訳に携わったことがあれば、彼はおそらく多くの標準があることを知っているでしょう、そして詳細に調べると、ソリューションは次のようになります：GitHubにあるテストファイルと何らかのドキュメントテキストがあります。 何をする必要がありますか？ スケルトンとXLIFF翻訳の2つのファイルを生成する必要があります。



スケルトンはブロックの書式設定です。つまり、テキストの一部をそのようなプレースホルダーで数字に置き換えます。



XLIFFは特別な形式であり、説明され、仕様があり、すべてが単純です。 最も重要なことは、XLIFFにユニットがあり、ユニットIDがスケルトンで置き換えたセグメントに対応していることです。



また、各ユニットには、ソースとターゲットの2つのタグがあります。 ソースタグには、スケルトンで置換したテキストが正確に含まれており、ターゲットフィールドは最初は空です。 このXLIFFを翻訳者に渡します。 これで、ターゲットフィールドに入力されます。 翻訳後、逆生成を行い、英語版のドキュメントを取得します。



同時に、翻訳はどこにも消えませんが、特別な標準化されたXMLファイルTMXに保存されます。 ソースとターゲットの2つの値があります。 これはどのように役立ちますか？ 以前の状況に戻ります。 寄稿者、開発者、または別のテクニカルライターが来て、元のドキュメントの何かを修正しました。 たとえば、ロシア語版では。

まだXLIFFを生成して翻訳者に渡し、プログラムに保存されているデータベースを使用して、変更されたセグメントを正確に翻訳します。 100パーセント一致する行は変換されません。それら自体はオートコレクトによって置き換えられます。 したがって、変更されたものを探す問題はもうありません。 少なくとも何らかの形で変更されたすべての行が翻訳に表示されることを保証します。 次に、ドキュメントの英語版を生成します。すべてが簡単です。 既成の解決策があるようです-確かにそうあるべきだからです。



ABBYYのsmartcat.ai 、 Googleのソリューション、 Matecatがあります 。 しかし、これらのソリューションの全体的な欠点は、Markdownをサポートしていないことです。Markdownには、作成方法に関する単一の標準がありません。 そして、彼らはそれをバイパスし、標準化されたフォーマットをサポートします。 先週、matecatでMarkdownをチェックしたところ、すべてが赤くなりました。 マークダウンは気取らないものでしたが。

たとえば、複雑なネストを備えたツールを取り上げます。 コードがあり、その中に3つのバックニクスがあり、そこにJSDocがあり、99％ですべてに対処します。ネストのレベルは任意です。

これらのサービスの2番目の致命的な欠陥は、GitHubと統合されないことです。 ユーザーがリンクを介して私たちのところに来て、何かを修正したいのですが、統合されません。

私たちは皆これについて議論しました。 ロシア語のソース文書があり、別の言語に翻訳すると、特定のペア、つまりロシア語への堅固な添付ファイルがあります。 ユーザーがどこから来ても、その場でTMXを編集できるように、この添付ファイルを削除する作業を行っています。 ロシア語版または英語版があり、生成中にTMXを直接展開する必要があります。 これはまだ決定されていません。

サイトの組み立ては、執筆からサイトに掲載するまでのMarkdown文書のパスの一般的なレビューの一部として検討することを提案します。



ワークフローはどのように見えますか？ 作業計画が作成され、すべての情報が収集されたとします。 Markdownと言えば、構文の配置に従うことが重要です。 その後、自動テストが行​​われ、リンティングの事前コミットが行われます。 次に、ドキュメントはGitHubに送られます。 英語版が必要な場合は、ドキュメントをローカライズします。 アセンブリが行われた後、2つのストーリーがあります。 1つは、1対1のドキュメントがページにマップされるときであり、2つ目は、さまざまなインライン例を構築する必要があるときです。 ページなどにiframeを埋め込む必要があります。これをすべて実行できるツール、ポットがあります。 彼はリンクを置き換えることができ、さまざまなMarkdownドキュメントを1つに結合し、インラインの例を構築できます。 次に、サイトで計算が行われます。

なぜウェブサイトが必要なのですか？ gulp.jsのように、すべてのドキュメントをMarkdownに保存しないのはなぜですか？

答えは明らかです。単一のエントリポイントが必要です。 100を超えるリポジトリがあり、これらのドキュメントを1か所で収集する必要があります。 検索、ナビゲーション、および実例も必要です。 ライブの例は次のようになります。



GitHubとサイト上の同じドキュメントは、異なる方法でレンダリングされます。 新しいウィンドウで開き、ボタンをクリックして、HTMLを確認できます。 とても便利です。



私たちのレシピは何ですか？ どうする？ まず第一に-ニーズを決定する。 それらが私たちのものに似ている場合は、Markdown構文に制限を導入し、用語に従い、自動チェックを行い、翻訳メモリを使用します。 ツール： remark -lint 、 yaspeller 、 md2xliff 。 ありがとう