¿Cómo puedo escribir una mejor documentación?

Answer 1

Hay muchos tipos diferentes de “documentación”: es decir, hay muchas formas diferentes de ayudar a los usuarios a aprender cómo usar su software.

Aquí hay una descripción rápida:

Documentación escrita

1. README : su primer contacto con un usuario. Incluya una descripción, ejemplos rápidos, guía de inicio rápido, enlaces a documentación adicional y detalles legales / del proyecto.
2. Tutorial : el archivo README atrapó al usuario, el tutorial le muestra los alrededores. Dirija a los usuarios paso a paso a través de casos de uso comunes y características clave del proyecto.
3. Guía de referencia : ahora que el usuario ha seguido el tutorial, finalmente sabrá qué preguntas hacer. La guía de referencia debe proporcionar las respuestas en forma de un catálogo organizado y con capacidad de búsqueda de documentación detallada.

Documentación del código

1. Nombramiento, patrones de diseño, sistema de tipos : cada programa define un mini-DSL en forma de nombres de paquetes, clases, variables y métodos. Elija los nombres sabiamente para que su código haga un buen trabajo al comunicar su intención. Los patrones de diseño que se proporcionan son un vocabulario compartido, lo que facilita el nombramiento. Los idiomas seguros de tipo pueden proporcionar aún más información sobre su código de forma automática, especialmente con buenos IDE.
2. Documentos y comentarios de la API : el código te dice cómo, los comentarios te dicen por qué . Los documentos de la API son comentarios para cada método: use herramientas de su idioma para exponerlos a los usuarios.
3. Código de ejemplo : muchos desarrolladores no utilizarán RTFM y preferirán copiar y pegar, así que asegúrese de tener disponible un código de ejemplo de alta calidad para demostrar el uso idiomático / adecuado de su proyecto.

Documentación comunitaria

1. Herramientas de gestión de proyectos : el software de seguimiento de errores y gestión de proyectos contiene mucha información sobre el pasado, el presente y el futuro de un proyecto. Hazlo accesible y buscable.
2. Listas de correo y tableros de preguntas y respuestas : la documentación no puede responder a todas las preguntas, por lo que muchos programadores recurren a herramientas como Grupos de Google, StackOverflow y Quora para obtener respuestas. Cultive estas comunidades, ya que contendrán información vital, especialmente sobre las partes confusas de su proyecto.
3. Publicaciones de blog y charlas : construya una comunidad alrededor de su proyecto, ¡y otras personas comenzarán a crear documentación para usted! Las publicaciones de blog y las charlas capturan experiencias del mundo real, que son una excelente herramienta de aprendizaje.

Escribí una guía más detallada con muchos ejemplos aquí: Eres lo que documentas.

Answer 2

Dirigir su documento a su audiencia es el primer lugar para comenzar.
Dependiendo de para quién está preparando la documentación, como el administrador del sistema, el administrador de datos, el usuario final, los desarrolladores, el propietario del proceso (generalmente el tipo con el dinero), la cantidad de complejidad y el contenido varían.

Existen estándares para la documentación de software que debe prepararse: P +, 2167a, etc., y cualquier estándar interno, como las guías de estilo de Microsoft. Debe seguir los estándares tanto como sea posible.

La mayoría de la documentación comienza con una breve introducción que explica el contenido y el propósito del contenido. Las ilustraciones como los modelos son útiles para guiar al lector a través de un conjunto de lógica. Use la tabla de contenido, etc., para ayudar a los lectores a encontrar el material necesario rápidamente.

Los documentos gerenciales tienden a ser:
1. Una ilustración simple y comprensible de 1 página que explica
2. Una declaración que diga qué debe hacer él o ella, especialmente cualquier acción que deban tomar de inmediato, junto con explicaciones de respaldo que expliquen por qué

Los documentos para otros desarrolladores deben contener:
1. Diagramas que explican el flujo de información a través del sistema y dónde se crea, modifica, elimina o almacena
2. Diagramas que explican la interfaz de usuario.
3. Diagramas o explicaciones sobre dónde está el software, cómo funciona y a qué nivel se utiliza
4. Todos los nombres de variables, salidas, datos, entradas y nombres de rutinas deben explicarse por sí mismos o documentarse, por ejemplo, una variable llamada j es una mala elección a menos que se explique.
El propósito es revisar el sistema con facilidad.

Los documentos para los usuarios deben usar un lenguaje simple y deben evitar términos técnicos inexplicables y evitar siglas en la mayor medida posible. Ellos deberían:
1. Sea tarea específica y completa
2. Debe proporcionar advertencias
3. Debe identificar puntos clave de contacto
4. Debe evitar largas explicaciones sobre cosas que al usuario no le importan
5. Debe tener un punto inicial y final específico
6. Debe ser encontrable

Mantenga un tono optimista, informativo y profesional.

Answer 3

1. Mantenlo corto y gramaticalmente correcto
2. Suponga que su audiencia no sabe nada sobre el tema.
3. Asegúrese de que cada paso del procedimiento esté separado
4. Sígalo usted mismo para ver si funciona
5. Haga que alguien descrito en el n. ° 2 lo pruebe
6. Publíquelo y habilite los comentarios de los usuarios
7. Manténgalo actualizado, tanto con cambios de versión como cambios válidos solicitados por el usuario

Answer 4

Aprender la escritura precisa.
escritura precisa – Búsqueda de Google

Base de datos MakeMovies