効果的なC ++ライブラリのWebサイトとドキュメントの作成

C ++ライブラリを作成することは、他のユーザーが使用できるようにドキュメント化することも意味します。また、ドキュメントの品質は劇的に異なる可能性があります。

C ++ライブラリのWebサイトは、最も効果的になるようにどのように構成すべきですか？

私は、「最も効果的な」ことを、図書館の利害関係者の3つの特定のグループに分割することで構成します。

1. 新規ユーザーは、1つのステップから次のステップに明確に流れる、優れた簡単な導入、ダウンロード、セットアップ、およびドキュメントが必要です。

2. 経験豊富なユーザーは、必要な詳細にすばやくアクセスできる確かなリファレンスと、新しい更新に関する明確な情報が必要です。

3. 新しい寄稿者は、寄稿をライブラリーに取り込むために実行する必要があるステップをカバーする方法をガイドする必要があります。

私は彼らが見たり使用したりするものにとても満足する方法を見つけたいと思います。この質問は、プロのプログラミングとユーザーエクスペリエンスとの間のちょっとしたクロスです。

特定の例では、Boostはライブラリの最高のコレクションの1つですが、初期インストール、リファレンスドキュメント、および貢献方法の把握はやや混乱を招く可能性があります。

一方、cppreference.comとSGI STLのドキュメントは、説明、リンク、および例があり、非常に明確で有用であることがわかりました。

例は単なる意見であり、他の例は異なる場合がありますが、それは私が質問している質問にコンテキストを与えるのに役立ちます。

私の以前の会社では、ドキュメントの生成を開始し、CIジョブを毎晩実行し、それをチームのwikiが参照する一連のWebページとして投稿しました。

あなたの質問へのコメントで提案されたように、doxygenを使用しました。バージョン1.8で導入された私が本当に気に入ったことの1つは、マークダウンドキュメントのディレクトリ（またはツリー全体）を作成できることでしたが、それ以前は、doxygenは純粋にソースファイルから生成されていました。

私たちが持っていた構造は、さまざまな場所へのリンクを持つウェルカム画面（マークダウン）でした。それらの1つは、製品の30,000フィートの視野を示し、主要なサービスを強調する製品アーキテクチャでした。次に、そのページから、各サービスを拡張し、各サービスの非常に高レベルのデザインを提示する他のマークダウンページに「いいね！」がありました（10,000フィートのビュー？）。

また、メインページから、いくつかの一般的なユーティリティ/フレームワークコードの使用方法を説明するために作成したユーザーガイドのコレクションへのリンクがありました。

また、既存の設計ドキュメント（MS Wordで作成され、共有ポイントに保存されている）を、実際には予想よりも簡単であることが判明したdoxygen形式に徐々に移行し始めました。個別にエクスポートしてJPEGとして保存する必要があったダイアグラムがなければ、20〜30ページのデザインドキュメントを約15〜30分でdoxygenマークアップ形式に変換でき、協同組合がそれを行うのは非常に簡単でした^{（ *）}。

同じソースからHTMLまたはPDFを生成できること以外に、このタイプのドキュメンテーションにdoxygenを使用することで私が好きだった美しさは、ヘッダーファイルを解析して生成されたクラス/関数のリファレンスページにすべてのドキュメンテーションを直接結び付けることができたことです。したがって、「ようこそ」->「アーキテクチャ」->「設計」->右からクラスレベルのドキュメントに至るまで、非常に優れた構造でした。

そしてすべてがマークダウンにあったので、コンテンツを生成するのは非常に簡単であり（エンジニアのチームにMS Wordスタイルを正しく使用する方法を説明するよりもはるかに簡単です）、ドキュメントがソースコードとともにチェックインされました。新しいバージョンが導入され、設計/アーキテクチャが変更され、ドキュメントは常にそれと同期されたままになります。