ruby / ruby/optparse

How to handle redundancy between params doc and tutorial doc

Offen
#20 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Dieses Issue hat noch niemand übernommen.

documentation
Vorherrschende Sprache
Ruby
Sterne
71
Forks
27
Ø Merge
3 Std. 3 Min.
Gemergte PRs (30 T.)
2

Beschreibung

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.

Beitragsleitfaden

Für dieses Repository ist kein Beitragsleitfaden indexiert

Erste Schritte

  1. Lies das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreib ins Issue, dass du es übernimmst — das erspart doppelte Arbeit.
  3. Forke das Repository und arbeite in einem Branch.
  4. Öffne einen Pull Request, der die Issue-Nummer nennt.

Rechercherichtung

Beginne damit, die Dokumentation zu den Parametern mit der Tutorial-Dokumentation zu vergleichen, wobei du dich auf deren erklärende Texte, Beispiele und Links konzentrierst. Die Arbeit ist abgeschlossen, wenn das Projekt eine vereinbarte Abgrenzung zwischen den beiden Dokumenten hat und übermäßige Redundanz reduziert ist, ohne dass Tutorial-Leser auf häufige Links angewiesen sind.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Bereich
documentation
Issue-Typ
Dokumentation
Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Aktivitätsstatus
Veraltet
Klarheit
Muss geklärt werden
Anfängerfreundlichkeit
20/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.