ruby / ruby/optparse

How to handle redundancy between params doc and tutorial doc

オープン
#20 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

まだ誰も着手していません。

documentation
主要言語
Ruby
スター
71
フォーク
27
平均マージ
3時間 3分
マージ済み PR(30日)
2

説明

As I said in an earlier PR, my aim is for:

  • The parameters doc to be about what the parameters do.
  • The tutorial doc to be about what the user can do.

There will necessarily be considerable overlap, both the text and in the examples, but I'd like to avoid excessive redundancy.

I don't want the tutorial to "link out" very often. The tutorial reader is entitled to have the relevant material in-line, not linked to.

I'm thinking about having the parameters doc retain its explanatory text, but link to the specific tutorial section for examples. This would make the parameters doc much shorter -- a Good Thing in itself -- and also make the reader aware of the tutorial doc -- possibly another Good Thing.

I will value opinions.

コントリビューションガイド

このリポジトリのコントリビューションガイドは索引されていません

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

調査の方向性

まず、パラメータのドキュメントとチュートリアルのドキュメントを比較し、説明文、例、リンクに重点を置きます。2つのドキュメントの間にプロジェクトとして合意された境界ができ、チュートリアルの読者が頻繁なリンクに依存することなく、過度な重複が削減されれば、作業は完了です。

索引モデルが issue の本文から書いたものです。

評価

領域
documentation
issue の種類
ドキュメント
難易度
5/5
見積もり時間
1週間以上
活発さ
停滞
明瞭さ
説明が足りない
初心者へのやさしさ
20/100

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。