visual studio generar documentar documentacion codigo documentation

documentation - studio - documentar codigo c#



¿Qué es una buena documentación en línea? (15)

Creo que PHP tiene la mejor documentación en línea para un idioma.

Si hay una función que no conozco para usar, iría a php.net/ function-name .

Por ejemplo, si estoy buscando la función debug_backtrace, visitaría php.net/debug_backtrace . Si mal escrito el nombre de la función o no existe, el sitio haría todo lo posible para encontrar la función correcta y redirigir allí. De lo contrario, le mostrará una búsqueda en la función de PHP que esté más cerca de la función que está buscando.

¿Qué se necesita para que la documentación en línea sea útil e interesante de leer?

Descargo: Si bien esta pregunta tiene orígenes egoístas (estoy escribiendo documentación, y, naturalmente, quiero que sea la mejor), estoy seguro de que otras personas pueden aprovechar las respuestas. Además, aunque la documentación no es de programación, todavía creo que es adecuado preguntar esto aquí, ya que es necesario documentar cosas si programa cosas.

Elaboración: esta pregunta es específica para la documentación en línea, porque creo que hay una gran diferencia entre un tomo en 1500 páginas y la dinámica de una página web / sitio web.

Asumiendo que hay un nuevo y emocionante servidor llamado WhizBangDaemon del cual no sabes casi nada, y has decidido intentarlo y aprenderlo en tu tiempo libre. ¿Qué tipo de secciones debería haber, para que la documentación sea útil e interesante y que no deje de leerla?

Por favor, siéntase libre de proporcionar enlaces a buenos ejemplos existentes y explicaciones de por qué le gustan.

Otro enfoque para esta pregunta es: ¿Qué tipo de obstáculos te hacen perder interés en leer un conjunto de documentación?

Respuestas

Recapitulando algunos temas recurrentes entre las respuestas:

  • navegación rápida
  • texto introductorio / tutoriales / ejemplos
  • no solo la documentación de la API
  • dividido en muchas partes pequeñas (podría estar relacionado con el primer punto)
  • Concisa y al grano
  • instalaciones de búsqueda
  • #anchors para vincular
  • formato descargable disponible

Divida la información, algunas personas que quieran probar su producto pueden querer ver solo tutoriales o ejemplos, me refiero a ejemplos bastante cortos.

Por otro lado, alguien que ya compró su producto quiere distinguir la mayor parte, así que cree una especificación API completa con índices y capacidades de búsqueda, vincule la información entre páginas, agregue algunos ejemplos para la API y simplemente no agregue lo que los parámetros reciben y qué devuelve el método / función, etc. Por supuesto que en el caso de que vendas algo para programadores.

¡Da ejemplos del mundo real! No solo agregue información de referencia, sino ejemplos de códigos o ejemplos de entornos de trabajo reales que puedan ser útiles para alguien que aplicará su software para ser productivo y completar una tarea y no solo para aprender.

Eso es lo que busco en la documentación, si los tiene, los compraré;)

Ejemplos de códigos reales , así como mínimos.

Los ejemplos de Hello-world-style son geniales, pero debemos conocer todas las advertencias que deben tenerse en cuenta en el código de producción, es decir, las implicaciones de seguridad, la inseguridad del hilo, etc.

Estoy de acuerdo con muchos otros carteles aquí, dos cosas que no están realmente contenidas pero que son muy importantes para mí:

  • tiene que ser RÁPIDO , tanto la navegación normal como la búsqueda
  • tiene que ser enlazable, quiero poder enviarle a alguien un enlace a una parte específica de la documentación

Como un ejemplo negativo: http://livedocs.adobe.com siempre se siente lento y muchas veces no se puede enlazar :-(

PD: y siempre es bueno proporcionar una versión descargable para su uso fuera de línea.

La documentación de Django es bastante sorprendente ( http://docs.djangoproject.com/ ), es bastante completa y fácil de leer, y hace que sea más rápido encontrar lo que necesita.

  • Texto conciso (no se necesita mucha lectura, por lo tanto, menos tiempo para leer documentos)
  • Buenos ejemplos
  • Encuentre rápidamente lo que está buscando (sin necesidad de un motor de búsqueda, pero como en una gran página de índice)

La documentación en línea (al menos la versión canónica estándar) debe ser breve y concisa. Pero entonces la versión canónica de toda la documentación debe ser breve y concisa, por lo tanto, la documentación en línea solo necesita duplicar el canon.

Estoy particularmente descontento con la suposición detrás de la declaración en la pregunta sobre una xpectación de "1500 páginas y algo así como" para las buenas versiones impresas. Para mí, ese no es un buen ejemplo de ningún tipo de documentación salvo una enciclopedia.

Y debe ser descargable, porque es donde me gusta que mi documentación esté, en mi computadora portátil, disponible cuando esté.

Observe que hasta ahora han habido pocos ejemplos consensuados propuestos de buena documentación. Considere si la complejidad de las características enumeradas en las respuestas no está funcionando en contra de la viabilidad de hacerlo de esa manera en primer lugar. Todo eso es genial en algún contexto, pero cuando se supone que es la fuente principal, es demasiado abrumador (e imposible de mantener actual e internamente consistente.

Sí, tengo la edad suficiente para preferir las páginas man de Unix. Comience con esos, y tomaré (o no) el resto cuando lo necesite o lo necesite.

Muchas empresas no parecen darse cuenta de lo importante que es el documento.

Escribir documentación es una gran parte de mi trabajo. Es el trabajo que nadie quiere, pero al menos es tan importante como cualquier otro en el equipo de desarrollo. Me di cuenta de esto cada vez más ya que he trabajado con varios lenguajes y herramientas y he experimentado el dolor del documento pobre o inexistente y las alegrías del buen doc.

Las cosas más importantes:

  1. Sea claro y conciso
  2. Un buen ejemplo vale más que mil palabras
  3. Ejemplos útiles (no es lo mismo que # 2)
  4. Agregue ejemplos de cosas que un usuario típico / la mayoría de los usuarios desearía / necesitaría hacer con lo que esté documentando.
  5. ¿He mencionado ejemplos ?

Particularidades: Odio el hecho de que los documentos API de Java prácticamente no tienen ejemplos. Busque prácticamente cualquier clase o método, y nada, ni siquiera un trazador de líneas. No es que un trazador de líneas sea suficiente en la mayoría de los casos, pero ni siquiera podrían molestarse con eso.

Muchos proyectos de código abierto exitosos demuestran cuán buena puede ser la documentación en línea.

Algunos aspectos son:

  • A hoy. Si la documentación ya no está actualizada, puede convertirse en un impedimento para mostrar.
  • Muchas documentaciones en línea comienzan con un breve tutorial. Muestran algunos aspectos clave del software y mantienen al usuario consciente e interesado para profundizar.
  • A menudo, HowTos o preguntas frecuentes son muy útiles. Muchos usuarios eligen no leer documentaciones y simplemente probarlo. En algún momento, es muy probable que los usuarios hagan la misma pregunta una y otra vez. Tenga en cuenta lo que los usuarios pueden pedir y lo que ya han pedido.
  • Para los usuarios interesados, proporcione información detallada en una documentación básica .
  • Considere también pensar en la audiencia de la documentación. Como autor de documentación, creo que es muy útil indicar claramente para qué audiencia es la documentación y qué tipo de conocimiento ya deberían tener. Esto me obliga a ser específico y conciso. De esta manera, puedo terminar separando la documentación en diferentes partes distintas, lo que hace que la documentación sea muy estructurada.

Si ya tiene una documentación de "1500 páginas como algo parecido", puede completar algunos tutoriales, HowTos y preguntas frecuentes, y eso agilizaría la documentación. Cuando el software evoluciona, puede refactorizar la documentación del núcleo para una mayor legibilidad.

La parte más difícil es mantener la documentación actualizada. Escriba la documentación con los cambios futuros en mente.

Un montón de muestras de código mínimo . Uno por tarea Identifica las 5 tareas principales; Asegúrese de copiar y pegar su implementación de sus documentos y compilarla. Sí, volveré y leeré las explicaciones reales. Primero quiero ver algo de carne.

Esto hace una gran diferencia al evaluar bibliotecas. Todavía no sé de qué se trata Adobe Adán y Eva.

Una buena documentación debe explicar "por qué", no solo "qué". ¿Por qué querría usar esta característica? ¿Para qué escenarios es bueno?

Eso, y debe tener buenas instalaciones de búsqueda.

  • La capacidad de enviar comentarios es útil, ya que puede capturar documentación escrita desde una perspectiva diferente, o ideas en las que no había pensado originalmente.
  • Si tiene tiempo para permitir la verificación de los cambios al estilo wiki de la documentación, eso también puede generar dividendos similares.
  • buena instalación de búsqueda
  • muchos puntos de anclaje #bookmark en páginas largas, lo que permite hacer referencia fácilmente a las secciones en sitios como este
  • usar un formato flexible como DocBook permite que el manual se represente de varias maneras, como HTML, PDF, CHM, etc.

Buena documentación debe ser skimmable. Debe escribirse desde el punto de vista de que el 90% de los usuarios no estarán dispuestos a leer más del 10% del material. Siempre hay una desconexión entre el autor que se enfoca en escribir algo bueno y el lector que solo quiere relajar las cosas.

Use cualquier truco en el libro para hacer que la información más importante sea altamente visible. Especialmente advertencias o instrucciones.

En mi opinión, deberías pensar de manera simple al respecto. También puede instalar cualquier software wiki o intentar alquilar desde alguna empresa de hosting y crear su propia documentación sin ninguna limitación.

Gratis por ejemplo: screwturn

Odio personal de mascotas: proyectos que ejecutan doxygen sobre sus encabezados y piensan que la documentación está completa. Es absolutamente necesario material introductorio ... tutoriales, ejemplos de códigos de trabajo (preferiblemente independientes), una descripción general para señalar las clases más importantes en la documentación de referencia. Qt es uno de los mejores ejemplos de esto bien hecho en mi humilde opinión.

Además, asegúrese de proporcionar un servicio de búsqueda decente (incluso si solo se trata de un redireccionamiento a una búsqueda en google específica del sitio). Esta es una de las razones por las que a veces prefiero los archivos de MS .chm a los manuales en línea alojados en la web.