Pecan: Esquema de la documentación

@robkooper y @ashiklom Intentaron combinar sus dos ideas de un esquema. @KristinaRiemer y @bailsofhay estarían bien en recibir sus comentarios. Vamos a empezar a implementar esto pronto para que podamos mover las páginas a donde queramos antes de fin de mes.

Creo que esto se ve muy bien. ¿Esto es solo reorganizar el material existente, no agregar nada?

Al hacer esto, el capítulo 41 debería ir antes del 40.

@KristinaRiemer Sí, solo voy a mover las cosas. Mientras tanto, podemos identificar las cosas que faltan y generar problemas. Tenga en cuenta que esto está etiquetado como un problema "épico", por lo que estos otros problemas se pueden vincular en este problema para que podamos mantenernos organizados.

Solo estaba buscando en la documentación algo de jerga para usar en una redacción rápida sobre lo que hago. Me di cuenta de que el documento no tiene la mejor explicación de por qué alguien querría usar nuez (específicamente, falta alguna explicación para el análisis de incertidumbre). Tendría sentido poner esto en la sección "Descripción general del proyecto" del documento disponible actual, no estoy seguro de dónde agregarlo para el documento reorganizado en el que estamos trabajando.

Enlace de @infotroph sobre documentación: https://www.divio.com/blog/documentation/

Enlace de @infotroph sobre documentación: https://www.divio.com/blog/documentation/

Más contexto: esta pieza presenta un caso fuertemente argumentado de que hay cuatro tipos distintos de documentación de software, y que todos los proyectos bien documentados deben tener los cuatro como secciones explícitamente separadas:

• tutoriales , para enseñar a los principiantes lo que hace su herramienta utilizando ejemplos paso a paso que están garantizados para funcionar exactamente como se describe en todo momento
• procedimientos , la sección de libros de cocina donde los usuarios pueden ir para responder preguntas del tipo "¿Cómo ...?", que contiene solo los detalles que necesitan para una pregunta determinada
• referencia , para los detalles de la página de manual sobre cómo llamar a las cosas, qué protocolos hablan y qué valores devuelven
• discusión , donde explica por qué las cosas funcionan como lo hacen, proporciona información de fondo, aconseja sobre buenas prácticas y malas prácticas y, de lo contrario, brinda un contexto que no encaja en las otras secciones.

Este problema está obsoleto porque ha estado abierto los 365 días sin actividad.

A largo plazo, creo que el concepto de tutorial / cómo hacer / referencia es sólido y que aún podríamos aclarar los documentos aplicándolo de manera más uniforme. Pero la reorganización que se discutió originalmente aquí se ha implementado lo suficiente como para cerrar este problema y alentar nuevos subprocesos para cualquier limpieza adicional.