¿Cómo crear documentación para un proyecto de software? ¿Qué debo escribir en la documentación?

Por lo general, la razón por la cual existe la documentación es porque no desea dedicar su tiempo a responder las mismas preguntas una y otra vez. Así que supongo que un buen punto de partida sería mirar el tipo de preguntas que hacen sus clientes y ver si hay preguntas recurrentes. Si los hay, asegúrese de que sean parte de su documentación.

Una vez que tenga una idea del tipo de artículos de la base de conocimiento que desea escribir, probablemente tenga sentido organizar el contenido para que sus usuarios puedan navegar fácilmente. Por ejemplo: haga un capítulo completo / elemento de menú / espacio sobre cómo ayudar a las personas a comenzar (cómo instalo y configuro el software, cuáles son los siguientes pasos).

Visite Confluence Documentation Home para inspirarse. Por cierto, puede usar Confluence para escribir y publicar su documentación (entre muchas otras cosas).

La forma en que abordaría la creación de documentación es algo como esto:

Identificar flujos de trabajo

Identifique flujos de trabajo individuales en su software. Para comenzar, cree diagramas de flujo para cada flujo de trabajo o tarea principal que se pueda hacer con su software. Estas son las tareas que sus usuarios realizarán en su software. Entonces, la primera pregunta que podría venir a la mente de un usuario es “¿Cómo realizo la Tarea X?”.

El objetivo de su documentación debe ser responder esa pregunta.

Convertir flujos de trabajo en instrucciones

El siguiente paso es convertir los flujos de trabajo representados por los diagramas de flujo en instrucciones. Dependiendo de la complejidad de la tarea de nivel superior, es posible que deba dividir cada tarea principal en tareas menores y escribir instrucciones para cada tarea menor.

Esto debería darle una buena base y también ser suficiente para que el cliente despegue.

El camino a seguir

Después de completar esta recopilación inicial de temas de ayuda, su objetivo debe ser recopilar y clasificar las preguntas de todas las fuentes posibles, incluidas las que obtiene a través de consultas de soporte técnico, preguntas técnicas de preventa, quejas de clientes, etc. Cuando estudie estas preguntas detenidamente , verá un patrón emergente que le dará una idea de las fortalezas y debilidades de su documentación actual.

Esta comprensión de las fortalezas y debilidades le indicará el camino a seguir. Este ejercicio le dirá qué contenido nuevo necesita crear, qué contenido es útil, qué temas no son útiles para los usuarios, etc.

Un ciclo continuo

En este momento, ya estará en el ciclo de vida del desarrollo de documentación. Y tomará vida propia. Lo único que debe tener en cuenta es que su documentación nunca debe desviarse del objetivo de ayudar a los usuarios a cumplir sus tareas u objetivos.

More Interesting

¿Por qué las computadoras entienden solo la lógica 0 y 1?

¿Qué trabajos puede hacer un estudiante de secundaria en las startups?

Se me ocurrió la idea de un proyecto, lo ejecuté y seré el primer autor de la publicación. Mi IP solicitó presentarlo por primera vez en una conferencia antes de su publicación. ¿Debería dejarlo?

¿Qué me estoy perdiendo si estoy usando Windows 7 en lugar de Linux / Ubuntu?

¿Cómo puede determinar eficientemente el k-ésimo elemento máximo en un árbol de búsqueda binario?

Cómo ganar experiencia en Machine Learning

¿Qué tecnología utiliza Netflix (y otros servicios de transmisión) para evitar que alguien capture una película o incluso tome una captura de pantalla? Soy estudiante de informática, y me molesta que no pueda entender cómo funciona.

¿Qué motor basado en reglas sirve mejor al campo de IoT teniendo en cuenta el aspecto de procesamiento de eventos distribuidos (CEP)?

¿Existen universidades / colegios en la India que sean buenos para obtener una maestría en aprendizaje automático?

¿Cómo es asistir al campamento de selección de indios para IOI?

¿Qué es mejor: Macbook Pro o Thinkpad T450 para informática?

¿Se puede reducir el problema de la clasificación al problema de unicidad del elemento?

¿Cuánto poder de procesamiento se necesitaría para simular la tierra en átomos?

¿Qué otros laboratorios / profesores tienen creencias / enfoques similares para el futuro de la IA como el 'Algoritmo Maestro' del Prof. Domingos?

¿Qué tipo de preguntas surgen en la prueba AMCAT para un estudiante de informática?