Guía de Estilo de Documentos

Guía de estilo. Regla # 1: Siga la guía de estilo. Regla # 2: Ver regla anterior.

TL; DR? ¡No hacemos eso aquí!

No hay resumen de esta página. La Guía de Estilo se debe leer en su totalidad y se debe seguir. La desviación de la Guía de Estilo se debe hacer después de la discusión, permitiendo que la Guía de Estilo cambie según sea necesario por motivos prácticos.

Cuando se utiliza una Guía de estilo, el portal de documentación tendrá una única voz para el lector. Sin una guía de estilo, nuestros lectores tendrán que ajustar sus expectativas para cada documento, por lo que es una experiencia menos que ideal con posibles errores u omisiones innecesarias.

Reglas Generales

• Trate de usar la menor cantidad de palabras posible y al mismo tiempo sea lo suficientemente descriptivo en sus instrucciones.

• Sea específico y no omita información importante o consideración que beneficiará la decisión informada del lector

• Para instrucciones de acción del usuario, ponga las palabras clave en negrita (Ejemplo: Abra Chrome, seleccione el campo de dirección en la parte superior y complete www.ether1.org)

• Use texto en cursiva para nombres y referencias cortas / citas

• Use tantas capturas de pantalla como sea posible para asistir visualmente su información y compagínese con la información de instrucciones de acción en negrita (consulte la guía anterior)

• Use etiquetas de código triple para distinguir los comandos de la terminal, los contenidos del editor de texto y los bloques de código

• Use etiquetas de código único para distinguir todo lo que encuentre necesario para destacar

• Use cotizaciones de bloque para notas, comentarios y citas / referencias extensas

Títulos, Encabezados y Resúmenes

• Cada palabra no conectiva (a menos que se use como primera palabra en el título) del Título estará en mayúscula (Ejemplo: Este es un Título de Muestra)

• Cada documento comienza con un Resumen, una Introducción o una sección de Descripción que explica los antecedentes detrás del documento y / o cualquier información importante. La mayoría de la gente solo usará esta sección, necesitamos hacerlo bien.

• Los títulos comienzan en el #/1er nivel.

• Divida su contenido en encabezados lógicos de segundo / tercer nivel para ayudar al lector a navegar por el contenido y encontrar información útil.

Enlaces

• Al hacer referencia a este portal de documentación, incluya siempre el enlace para facilitar su uso.

• Usa buenas descripciones para tus enlaces en general.

• En caso de duda, vincularlo para beneficio del lector.