How to handle redundancy between params doc and tutorial doc

Ouverte
#20 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub

Personne n'a encore pris cette issue.

Évaluation

Difficulté
5/5
Temps estimé
Plus d'une semaine
Accessibilité débutants
20/100
Type d'issue
Documentation
Clarté
À clarifier
Activité
À l'abandon
Domaine
documentation

Piste de recherche

Commencez par comparer la documentation des paramètres avec la documentation du tutoriel, en vous concentrant sur leurs textes explicatifs, leurs exemples et leurs liens. Le travail est terminé lorsque le projet dispose d’une séparation convenue entre les deux documents et que la redondance excessive a été réduite sans rendre les lecteurs du tutoriel dépendants de liens fréquents.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Description

documentation

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.

Langage dominant
Ruby
Étoiles
71
Forks
27
Merge moyen
3 h 3 min
PR mergées (30 j)
2

Guide de contribution

Aucun guide de contribution indexé pour ce dépôt

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de ruby/optparse

Toutes les issues de ruby/optparse

Issues similaires

Plus d'issues Ruby

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.