仕様を書いています。 パート2.ツール。 Wiki-すべてが手元に

仕様書を書くための複雑で珍しいプロセスをシンプルで、手頃な価格で、さらに楽しくすることができるツールについて話し続けます（ パート1.ツール-シンプルなものから始めます ）。 私は長い間、wikiをこれに適合させる方法について考えてきました。

それの由来-以下をお読みください。



謝辞

404フェスティバルでは、チームワークのためのさまざまなツールの使用に関する YandexのKonstantin Kolomeytsの報告に非常に興味がありました。 居心地の良いソファの専門家のコーナーでのさらなる会話と質問への回答は、さらに面白くて有益であることが判明しました。 これがスケールを長い審議から行動へと駆り立てたきっかけでした。



ツール要件の呼び出し

• 読みやすさ。
  
  これにより、すべてがシンプルになります。 仕様を読むために必要なのはブラウザだけです。 おそらく誰もがブラウザでの作業スキルを持っています:)
• 検索の便利さ。
  
  wikiで適切な記事を見つけるには2つの方法があります。
  
  
  1. ナビゲーション/リンク。 サイドバーとwikiの最初のページには、すべてのプロジェクトへのリンクがあり、メインページには内部プロセスの説明もあります。
     
     各プロジェクトのヘッドページには、このプロジェクトのすべての（またはほぼすべての）記事へのリンクがあります。 これは非常に大きな大きなページで、リンクのみで構成されています。 これらは、カテゴリ（プロセスの説明、ユーザーインターフェイス、サーバー間相互作用など）に分類されます。 これらの仕様へのリンクもありますが、まだそこにはありませんが、間違いなくあるはずです。
  2. 検索。 現在、ネイティブMediaWiki検索を使用しています。 （インターネットには、これまたはその高度な検索エンジンを固定する方法がたくさんあります。しかし今のところ、1つまたは2つのキーワードで1つの記事を見つけるのに十分なネイティブがあります。）
• 変更履歴 。 組み込みのツールで十分です。
• チームワーク 。 組み込みの競合解決ツールで十分です。 ドキュメント全体ではなく特定のセクションを編集している間、このような競合が発生する可能性は非常に少ないです。 これは私たちに週に一度しか起こりません。
• 編集自体の便利さ
  
  楽しみが始まります。 私には仕事がありました-私たちの同僚が私たちのツールを使いたいと思うようにすること。 このためには、単純で日常的な行動は勉強を必要とせず、通常の方法で行われることが必要です。 ツールキット（マークアップ言語、あらゆる種類の拡張機能）をさらに研究することで、作業の速度を上げたり、新しい機会を提供したりするために、即時かつ具体的なメリットがもたらされるはずです。
  
  以下では、編集を容易にするためにどのように戦ったかを説明します。
  
  
  
  ツールを収集します
  
  1） エンジン。 MediaWiki
  
  多くのWikiエンジンがあります。 私は一方が他方より優れていると断言することはありません。 私たちに合ったものを選びました。
  
  まず、無料です。 wikiに目を向けると、これが最終決定であるかどうか100％確信が持てなかったため、商用システムを購入するリスクを冒したくありませんでした。 さらに、その時点で（少し誇張しています）、すべてのWikiが同じ顔をしていました。
  
  第二に、実装の言語。 PHP / MySQL。 私たちはすでにそのようなサイトとそのような専門家を抱えており、必要に応じて、何かを引き締める準備ができていました。
  
  第三に、すべての種類の拡張機能が多数あります。
  
  そして最後に、ビッグネーム。 このエンジンがウィキペディアを引っ張るので、このエンジンが十分に信頼できることを望んでいました。
  
  
  
  2） 編集者。 WikEd + FCKEditor
  
  もちろん訪問したかったです。 新しいシステムは、それを使用するために習慣を変更する必要がある場合、敵意をもって認識されます。 この場合、テキストを扱うことはそのような習慣でした。 Wordでの作業方法は誰もが知っていました。 しかし、私はアナリストにあらゆる種類のマークアップ言語を習得するように強制したくありませんでした（非常に簡単ですが、メインの仕事には必要ありません）。 プログラマーにとっては、落ち着いていました。 htmlの後、wikiマークアップは単なるおとぎ話です。
  
  
  
  FCKEditorはwysiwygエディターです。 Wordのように見えます（私は一言で覚えていることを許してくれますが、人生はIT担当者なら誰でもWordで書くことができます。 だから、彼は言葉のように見えます。 ホットキーを含む。 テーブルを使用すると便利です。 他の記事へのリンクを作成すると便利です。入力したキーワードに対して、彼自身がいくつかの記事を選択できます。
  
  しかし、欠点もあります。 主なものはバッファを使用しています。 彼はフォーマットされたテキストをバッファに挿入することに同意します。 しかし、バッファから-イチジク。 プレーンテキストのみ。 予想外です。 段落を切り取り、文書の先頭に挿入したい-しかし、そうではない。 マウスで選択してドラッグする必要があります。 Wordからの挿入については話していません（しかし、古い仕様をどのように転送できますか？）
  
  2番目の大きなマイナス点は、テンプレートと構文拡張の内容が表示されないことです。 つまり、内部にゴミがあることが明らかです。 どれが見たいですか-別のウィンドウで見てください。 テキスト、スクリプトの説明、およびメモのコメント用のサンプルテンプレートが多数あるため、これは不便です。
  
  したがって、1人のエディターでは不十分でした。
  
  
  
  目が覚めた。 正反対。 対戦相手が不利なところに利点があります。 しかしその逆。
  
  マイナス面は、実際にはワイシウィグではないことです。 これはwikiマークアップエディターです。 太字は太字で、斜体は斜体で表示されますが、マークアップも表示されます。 したがって、読者がここで見るものを示していません。 プレビューを取得する必要があります。
  
  さらに、これはおそらくwikiマークアップに最適なエディターです。 彼女の訪問を好む人のために。
  
  プラス-バッファから書式設定されたテキストを貼り付ける機能。 特に-Wordから。 wikiマークアップへのその後の変換。
  
  マイナス-Internet Explorerでは機能しません。 不都合ですが、重要ではありません。 アナリストはfirefoxをマスターします。 オペラの悪いファン。 彼らはFirefoxに切り替えたくない。
  
  
  
  だから私たちは生きています。 2人のエディター。 タスクに応じて、一方から他方に切り替えます。 ドキュメントの元のバージョンは、FCKEditorで簡単に編集できます。 その中で-テーブルを操作します。 最終的なマークアップとメモの埋め込みは、WikEdではより便利です。
  
  
  
  3） エクスポート。 PDFBook + Wordにアップロードするためのファイルのファイナライズ。
  
  wikiを導入する際の質問の1つは、顧客と仕様をどのように調整するかということでした。 イントラネット上にウィキがあり、それを公開する機会はありません。 そして、顧客はどのようにコメントを書くことができますか？ wikiマークアップも学習しますか？ オプションではありません。
  
  オプション-ある種のユニバーサル形式にエクスポートします。 あなたは笑いますが、それは一言です。 PDFは読むことも印刷することもできますが、顧客はその中に何かを書いたり修正したりすることはありません。
  
  
  
  PDFBookでは、現在のページ（いわゆるバインダー）をPDFで保存できます。 バインダーは、箇条書きの形式で他のページへのリンクを含む特別なページです。 このページは将来の本の内容になり、リストされているすべてのページは章として含まれます。
  
  
  
  この拡張機能を少し確定しましたが、今ではWord文書も作成できるようになりました。
  
  この拡張機能を呼び出すためのリンクをサイドバーに追加しました。これで、任意のページをdocファイルまたはpdfファイルに保存できます。
  
  
  
  4） 画面フォームのスケッチ。 バルサミクモックアップ
  
  これは単なる奇跡です。 驚くほどシンプルで楽しいUIスケッチエディター。 対照的に、Visioに対するスケッチです。 結果の図面は、フリーハンドの鉛筆スケッチのように見えます。 そして、これがすべての美しさです。 Visioで描画する場合、スケッチはほとんど実際のインターフェイスのように見えるので、意外にも「美しく」したいです。 そして、バルサミクモックアップにはそのような誘惑はありません。 開発者と顧客の注意は、主なもの、つまりフォームの全体的なデザイン、構成、およびコントロールの位置に集中しています。 色、フォント、ピクセル精度の要素の配置などの取るに足らない瞬間に気を取られることなく、他の美しさ。 原則として、プロジェクトのフレームワーク内のスタイルガイドによって決定されます。
  
  別の便利な機能は、ビルディングブロック-コントロールです。 同時に、複雑なコントロール（複数列のテーブルやツリーなど）は、単純なコントロール（ボタンやラベル）ほど複雑ではありません。 Visioで木を作ろうとした人は誰でも私を理解するでしょう。
  
  これにより、Visioと比較してインターフェイスの描画速度が大幅に向上します。
  
  そして最後に、最も重要なプラス。 このことは、Wikiと見事に統合されています。 エディターは、Wikiページで実行されるAIRアプリケーションです。 また、その形式のスケッチは、Wikiに直接保存されます。 開発者サイトには、xWikiのオプションがあります。 しかし、軽いファイルの改訂により、MediaWikiでの起動が可能になりました。
  
  そして最後に私が言わなければならない-これは唯一の有料拡張機能です（私たちが使用しているすべての拡張機能です）。 しかし、それは価値があります。
  
  ところで、デスクトップ版があります。 （無料、5分ごとに自分で購入できる）。 私たちのアナリストは彼らを連れて行き、顧客を訪問します。
  
  
  
  5） UML。 PlantUML
  
  特別な構文を使用して、wikiページのテキストにUMLダイアグラムを直接「描画」できます。 そして、このテキスト記述に基づいて図面が作成されます。
  
  

       <uml>
         アリス->ボブ：認証リクエスト
         ボブ->アリス：認証応答
       </ uml>
  

  すべてのタイプの図がサポートされます（クラス図とシーケンスのみを知っている他の多くの無料プログラムとは異なります）。 もちろん、これはソースコードを生成する本格的なUMLデザインツールではありません。 しかし、設計上の決定を説明するには十分です。 1枚の写真は数百語に相当します。
  
  予想外に、この拡張機能の登場により、UMLは当社に定着しました。 その前に、ビジオで異なる図を描く試みがありました。 しかし、これは何とか力で、喜びなしで行われました。 ビデオは厳しすぎて要求が厳しいからだと思います。 PlantUMLは、それどころか、多くのことを許し、意味を推測しようとします。 したがって、彼と仕事をするのは楽しいことです。 彼らは私の同僚に取って代わりました。 誰もが突然UMLに夢中になりました。これについては非常に満足しています。
  
  
  
  6） 構文の色付け。 構文Highlight GeSHi
  
  多くの仕様では、図とともに、ある種のコードをすぐにスケッチします。 開発環境のように、明確で馴染みのあるものにする必要があります。 これは、構文の強調表示の拡張に役立ちます。 このバンドルは多数の言語をサポートしていますが、すべての言語を使用しているわけではありません。 私の愛するDelphiの場合、IDEのように見えるように設定を少しひねりました。
  
  
  
  結論
  
  適切に設定すると、Wikiは仕様を記述（保存、検索、読み取り）するための優れたツールになります。
  
  このような一般的なノートブック+鉛筆、任意の機会に書くことができます。 これが私たちがやろうとしていることです。 あなたは何かを知っています-あなたがそれを忘れるまでwikiでより速く書き留めてください。
  
  
  
  私はだましません。 行うには不便で、改善したいことがあります。 おそらくこれらはwikiの先天的な欠陥であるか、適切な拡張機能が見つからなかったのでしょう。 この記事はすでに非常に長く出ているので、トラブルのリストとウィッシュリストを次の記事に残します。
  
  
  
  関連リンク
  
  
  • MediaWiki：銀の弾丸またはスイスのナイフ？ -プレゼンテーション。 記事と同じ
  • kolomeetz.ru/blog-Wikiを企業ナレッジベースとして使用することに関するさまざまな記事。