How to handle redundancy between params doc and tutorial doc
Dieses Issue hat noch niemand übernommen.
- 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
- Lies das ganze Issue und danach den Beitragsleitfaden des Projekts.
- Schreib ins Issue, dass du es übernimmst — das erspart doppelte Arbeit.
- Forke das Repository und arbeite in einem Branch.
- Ö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