Pecan: Aperçu de la documentation

@robkooper et @ashiklom ont essayé de combiner vos deux idées d'un contour. @KristinaRiemer et @bailsofhay seraient bien d'avoir vos commentaires. Nous allons commencer à implémenter cela bientôt afin que nous puissions déplacer les pages où nous voulons avant la fin du mois.

Je pense que cela a l'air vraiment bien. Il s'agit simplement de réorganiser le matériel existant, sans rien ajouter ?

Lorsque vous faites cela, le chapitre 41 devrait en fait passer avant 40.

@KristinaRiemer Ouais, je vais juste faire bouger les choses. En attendant, nous pouvons identifier les choses qui manquent et créer des problèmes. Notez qu'il s'agit d'un problème « épique » afin que ces autres problèmes puissent être liés sous ce problème afin que nous puissions rester organisés.

Je cherchais juste dans la documentation un jargon à utiliser pour rédiger rapidement un article sur ce que je fais. J'ai réalisé que le document n'avait pas la meilleure explication pour expliquer pourquoi quelqu'un voudrait utiliser des noix de pécan (en particulier, il manque une explication pour l'analyse d'incertitude). Cela aurait du sens de mettre dans la section "Présentation du projet" du document actuellement disponible, sans savoir où l'ajouter pour le document réorganisé sur lequel nous travaillons.

Lien de @infotroph sur la documentation : https://www.divio.com/blog/documentation/

Lien de @infotroph sur la documentation : https://www.divio.com/blog/documentation/

Plus de contexte : cet article fait valoir avec force qu'il existe quatre types distincts de documentation logicielle et que tous les projets bien documentés doivent avoir les quatre sous forme de sections distinctes :

• tutoriels , pour enseigner aux débutants ce que fait votre outil en utilisant des exemples étape par étape qui sont garantis de fonctionner exactement comme décrit à chaque fois
• how-tos , la section livre de cuisine où les utilisateurs peuvent aller pour répondre aux questions du formulaire "Comment puis-je....?", contenant uniquement les détails dont ils ont besoin pour une question donnée
• reference , pour les détails de la page de manuel sur la façon d'appeler les choses, les protocoles qu'elles parlent et les valeurs qu'elles renvoient
• discussion , où vous expliquez pourquoi les choses fonctionnent comme elles le font, fournissez des informations de base, donnez des conseils sur les bonnes et les mauvaises pratiques et donnez un contexte qui ne correspond pas aux autres sections.

Ce numéro est périmé car il a été ouvert 365 jours sans activité.

Sur le long terme, je pense que le concept tutoriel/comment/référence est solide et qu'on pourrait encore clarifier la doc en l'appliquant plus uniformément. Mais la réorganisation discutée à l'origine ici a été suffisamment implémentée pour que je clos ce problème et encourage de nouveaux threads pour tout nettoyage ultérieur.