Pecan: Dokumentationsübersicht

@robkooper und @ashiklom Haben versucht, Ihre beiden Ideen einer Gliederung zu kombinieren. @KristinaRiemer und @bailsofhay würden sich über Feedback

Ich finde das sieht richtig gut aus. Dies ist nur das Umordnen von vorhandenem Material, nicht das Hinzufügen von etwas?

Wenn Sie dies tun, sollte Kapitel 41 tatsächlich vor 40 gehen.

@KristinaRiemer Ja, ich werde die Dinge einfach verschieben. In der Zwischenzeit können wir Dinge identifizieren, die fehlen und Probleme machen. Beachten Sie, dass dies als "episches" Problem gekennzeichnet ist, damit diese anderen Probleme unter diesem Problem verlinkt werden können, damit wir organisiert bleiben können.

Ich habe mich nur in der Dokumentation nach einer Fachsprache umgesehen, die ich für eine kurze Beschreibung meiner Tätigkeit verwenden kann. Mir wurde klar, dass das Dokument nicht die beste Erklärung dafür hat, warum jemand Pekannuss verwenden möchte (insbesondere fehlt jede Erklärung für die Unsicherheitsanalyse). Es wäre sinnvoll, dies in den Abschnitt "Projektübersicht" des aktuell verfügbaren Dokuments einzufügen, da Sie sich nicht sicher sind, wo Sie dies für das neu organisierte Dokument hinzufügen sollen, an dem wir arbeiten.

Link von @infotroph zur Dokumentation: https://www.divio.com/blog/documentation/

Link von @infotroph zur Dokumentation: https://www.divio.com/blog/documentation/

Mehr Kontext: In diesem Artikel wird stark argumentiert, dass es vier verschiedene Arten von Softwaredokumentation gibt und dass alle gut dokumentierten Projekte alle vier als explizit separate Abschnitte haben müssen:

• Tutorials , um Anfängern die Funktionsweise Ihres Tools anhand von Schritt-für-Schritt-Beispielen beizubringen, die garantiert jedes Mal genau wie beschrieben funktionieren
• How-Tos , der Kochbuchbereich, in dem Benutzer Fragen des Formulars "Wie kann ich....?" beantworten, die nur die Details enthalten, die sie für eine bestimmte Frage benötigen
• Referenz , für die Manpage-Details zum Aufrufen von Dingen, welche Protokolle sie sprechen und welche Werte sie zurückgeben
• Diskussion , in der Sie erklären, warum die Dinge so funktionieren, wie sie funktionieren, Hintergrundinformationen bereitstellen, Ratschläge zu guten und schlechten Praktiken geben und anderweitig Kontext angeben, der nicht in die anderen Abschnitte passt.

Dieses Problem ist veraltet, da es 365 Tage ohne Aktivität geöffnet war.

Langfristig denke ich, dass das Tutorial / How-to / Reference-Konzept solide ist und wir die Dokumente noch klarer machen könnten, indem wir es einheitlicher anwenden. Aber die ursprünglich hier besprochene Reorg wurde vollständig genug implementiert, dass ich dieses Problem schließe und neue Threads für weitere Aufräumarbeiten ermutige.