文書化するときに GIT を使用する

場合によっては、ドキュメント自体だけでなく、ドキュメントに取り組むプロセスも重要になることがあります。たとえば、プロジェクトの場合、作業の大部分は文書の準備に関連しており、プロセスが間違っているとエラーが発生したり、情報の損失さえも生じ、その結果、時間と利益の損失が発生する可能性があります。ただし、このトピックが仕事の中心ではなく周辺部にある場合でも、適切なプロセスによりドキュメントの品質が向上し、時間を節約できます。

ここで概説したアプローチは、 特定の実装例、参入障壁が低いです。技術的には、明日から新しい方法で仕事を始めることができます。

問題の定式化

ドキュメントまたはドキュメントのセットを作成する必要があります。おそらくこれは、プロジェクトの文書化やネットワークのログ記録、あるいはもっと単純なもの、たとえば、会社や部門のプロセスを説明する必要があるものかもしれません。一般に、私たちはテキスト、画像、記号を含むあらゆる文書または文書セットについて話します...次の事実によってタスクを複雑にしましょう。

1. この作業には共同作業、または従業員のグループまたは複数のグループの努力が含まれます
2. その結果、特定のテンプレートに従って作成された、企業スタイルの属性を備えた特定の形式のドキュメントが必要になります。具体的には、これが MS Word (.docx) であると仮定します。

10 年前なら、アプローチは単純でした。MS Word 文書を作成し、何らかの方法で変更作業を組織していただろう。

そして、このアプローチは今でも有効です。また、大規模なインテグレータがプロジェクトのドキュメントを作成するときにも使用されます。しかし、長期間にわたって多くの編集やディスカッションを行ってドキュメントに集中して作業する場合、このアプローチはあまり便利ではないことは直感的に明らかです。

例

私は大手インテグレーターで働いていたときに、この問題を非常に痛感しました。設計ドキュメントを変更するプロセスは次のとおりです。

1. エンジニアが最新バージョンの MS Word (.docx) ドキュメントをダウンロードする
2. 名前を変更します
3. ファッションを追跡するために変更を加える
4. 編集を加えたドキュメントを建築家に送信します
5. すべての修正のリストとコメントも送信します
6. アーキテクトが変更を分析する
7. すべて問題がなければ、これらの変更を最新バージョンのファイルにコピーし、バージョンを変更して、共有リソースにアップロードします。
8. コメントがある場合、ディスカッションが開始されます (電子メールまたは会議)
9. コンセンサスが得られる
10. さらなるポイント 3 ～ 9

作業は激しいものではありませんでしたが、それでもなんとか機能しました。しかし、ある時点からこのプロセスがプロジェクト全体のボトルネックとなり、問題が発生しました。重要なのは、複数のチームによって変更が頻繁かつ同時に行われるとすぐに状況が悪くなるということです。

そのため、予備テストの段階に移行すると、さまざまな問題が発生し始め、小さな点ではありますが、ドキュメントを頻繁に変更する必要がありました。4 つの異なるチームが毎日、ほぼ同時に議論を行いました。これらすべての変更は、1 人のエンジニア、つまり建築家を通じて行われました。プロジェクトの設計ファイルは巨大で、その結果、建築家は大量のコピーや編集を伴う日常的な作業に圧倒され、多くの間違いを犯し、すべてを再確認して再送信する必要があり、一般的にはほぼ次のような結果になりました。混沌。

この場合、このアプローチ、つまり MS Word 文書で作業するアプローチは非常に困難に機能し、問題が発生しました。

Git、マークダウン

上記の例で説明した問題に直面して、私はこの問題の調査を開始しました。
の使用を見ました 値下げ とともに Gitの 書類を作成するとき。

Git は開発ツールです。しかし、文書化プロセスにそれを使用しないのはなぜでしょうか?この場合、マルチユーザー作業の問題は解決されます。しかし、Git の機能を最大限に活用するには、テキスト ドキュメント形式が必要であり、MS Word 以外のツールを見つける必要があります。Markdown はこれらの目的に最適です。

Markdown は、単純なテキスト マークアップ言語です。通常の TXT ファイルで美しくデザインされたテキストを作成するように設計されています。 Markdown でドキュメントを作成する場合、Markdown と Git の組み合わせは自然に見えます。

そして、すべてがうまくいくでしょう。そして、2番目の条件がなければ、この時点でそれを終わらせることができます。「結果として、企業スタイルの属性を備え、以下に従って作成された、特定の形式の文書が必要です」特定のテンプレート」（そして、確かにそれがMS Wordになるということで最初に同意しました）。つまり、Markdown を使用する場合は、何らかの方法でこのファイルを必要なタイプの .docx に変換する必要があります。

異なる形式間で変換するためのプログラムがあります。 Pandoc.
このプログラムを使用すると、Markdown ファイルを .docx 形式に変換できます。
ただし、第一に、Markdown にあるものすべてが MS Word に変換されるわけではないこと、第二に、細いとはいえ小さな町である Markdown と比較すると、MS Word は国全体に相当することを理解する必要があります。 Word には、Markdown の形式にはないものが大量にあります。特定の Pandoc キーを使用して、Markdown 形式を目的の MS Word 形式に変換するだけでは済みません。したがって、通常は変換後に、結果の .docx ドキュメントを手動で「編集」する必要がありますが、これもまた時間がかかり、エラーにつながる可能性があります。

Pandoc が処理できないものを自動的に「終了」するスクリプトを作成できれば、それは理想的なソリューションになります。

MS Word と Markdown の機能は同一ではないため、一般的にこの問題を解決することは不可能だと思いますが、特定の状況、特定の要件に関連して解決できるでしょうか?私の経験から、それは可能であり、多くの状況、あるいはおそらくほとんどの状況で可能である可能性が高いことがわかりました。

特定の問題の解決策

したがって、私の場合、Pandoc を使用してファイルを変換した後、追加のファイル処理を手動で行う必要がありました。

• 表や図の見出し (キャプション) に自動番号付けを行うフィールドを Word に追加します。
• テーブルのスタイルを変更する

標準 (Pandoc) または既知の手段を使用してこれを行う方法が見つかりません。そこで私はPythonスクリプトを適用しました pywin32 パッケージ。その結果、完全自動化が実現しました。これで、1 つのコマンドで Markdown ファイルを希望の MS Word ドキュメント形式に変換できるようになりました。

詳細を見る ここで.

注意：

この例では、もちろん、抽象的な Markdown ファイルを変換しますが、まったく同じアプローチが「戦闘」ドキュメントに適用され、受け取った出力は、以前に手動で書式設定して受け取った MS Word ドキュメントとほぼ同じでした。 。

一般に、pywin32 を使用すると、MS Word ドキュメントをほぼ完全に制御できるため、ドキュメントを変更して、企業標準に必要な形式にすることができます。もちろん、VBA マクロなどの他のツールを使用しても同じ目標を達成できますが、私にとっては Python を使用する方が便利でした。

このアプローチの簡単な式は次のとおりです。

Markdown + Git -- (нечто) --> MS Word

「何か」が何であるかは関係ありません。私の場合は、Pandoc と pywin32 を使用した Python でした。好みは異なるかもしれませんが、重要なことはそれが可能であるということです。そしてこれがこの記事の主なメッセージです。

要約すると、このアプローチでは、Markdown ファイルのみを操作し、共同作業とバージョン管理には Git を使用し、必要な場合にのみ (クライアントにドキュメントを提供する場合など)、目的の形式でファイルを自動的に作成するという考えです (たとえば、MS Word )。

プロセス

多くの人にとって、ドキュメントを扱うプロセスがどのように構成されているかを理解するには、上記の式で十分だと思います。それでも、私は普段ネットワーク エンジニアに焦点を当てているので、作業プロセスがどのようになっているのか、そしてこれが MS Word ファイルを編集するアプローチとどのように異なるのかを一般的な用語で説明します。

具体的には、Git を操作するためのプラットフォームとして GitHub を選択します。次に、リポジトリを作成し、操作する予定の Markdown ファイルを master ブランチに配置する必要があります。

「github フロー」に基づいた簡単なプロセスを見ていきます。その説明はインターネット上と次の両方で見つけることができます。 ハブレ.

文書化に取り組んでいる人が 4 人いて、あなたもそのうちの 1 人であるとします。次に、たとえばこれらの人々の名前を使用して 4 つの追加のブランチが作成されます。全員がローカルの自分のブランチで作業し、必要な変更をすべて加えます。 gitコマンド.

ある程度の完成した作業が完了したら、プル リクエストを作成し、変更についてのディスカッションを開始します。おそらく、議論中に、何かを追加または変更する必要があることが判明するでしょう。この場合、必要な変更を加えて追加のプル リクエストを作成します。最終的に、変更が受け入れられ、master ブランチにマージされます (または破棄されます)。

もちろん、これはかなり一般的な説明です。詳細なプロセスを作成するには、開発者に連絡するか、知識のある人を見つけることをお勧めします。ただし、Git への参入障壁は非常に低いことに注意してください。これはプロトコルが単純であるということではありませんが、単純なことから始めることができます。まったくわからない場合は、数時間、場合によっては数日かけて学習してインストールした後、使い始めることができると思います。

たとえば、上記の例で説明したプロセスと比較して、このアプローチの利点は何ですか?

実際、プロセスは非常に似ており、置き換えただけです。

ファイルのコピー -> ブランチの作成
テキストを最終ファイルにコピー -> マージ
最新の変更を自分にコピー -> git pull/fetch
通信でのディスカッション -> プルリクエスト
トラックモード -> git diff
最新の承認済みバージョン -> master ブランチ
バックアップ (リモートサーバーへのコピー) -> git Push
...

したがって、すでに手動で行う必要があったすべての作業を自動化しました。

より高いレベルでは、次のことが可能になります

• 文書変更のための明確でシンプルかつ制御されたプロセスを作成する
• なぜなら最終的な文書 (この例では MS Word) が自動的に作成されるため、書式設定エラーの可能性が減ります。

注意：

そうは言っても、ドキュメント作成に一人で取り組んでいる場合でも、Git を使用すると作業がはるかに簡単になることは明らかだと思います。

これらすべてにより、ドキュメントの品質が向上し、作成時間が短縮されます。そしてもう 1 つの小さなボーナス - ネットワークを自動化するときに役立つ Git を学ぶことができます :)

新しいプロセスに切り替えるにはどうすればよいですか?

記事の冒頭で、明日からは新しい働き方を始められると書きました。自分の仕事を新しい方向に導くにはどうすればよいでしょうか?

従う必要がある可能性が高い一連の手順は次のとおりです。

• ドキュメントが非常に大きい場合は、部分に分割します
• 各部分を Markdown に変換します (たとえば、Pandoc を使用)
• いずれかの Markdown エディタをインストールします (私は使用しています Typora)
• ほとんどの場合、作成された Markdown ドキュメントの書式を調整する必要があります。
• 前の章で説明したプロセスの適用を開始します
• 同時に、タスクに合わせて変換スクリプトの変更を開始します (または独自のスクリプトを作成します)。

Markdwon 変換メカニズムを作成して完成させ、必要なドキュメントの出力タイプを完成させるまで待つ必要はありません。重要なのは、Markdown ファイルの変換手順をすぐに完全に自動化できなくても、Pandoc を使用して何らかの形式で変換し、それを手動で最終形式にすることができるということです。通常、これを頻繁に行う必要はありませんが、特定の段階の最後にのみ行う必要があります。この手動作業は、不便ではありますが、私の意見では、デバッグ段階では十分に許容でき、プロセスを「遅く」するべきではありません。多くの。

他のすべて (Markdown、Git、Pandoc、Typora) はすでに準備が整っており、それらの操作を開始するのに多くの労力や時間を必要としません。

出所： habr.com