Cómo escribir una instrucción de práctica básica

Con el aumento de la documentación online, ser administrador de sistemas ha pasado de ser hombre el comando es su único amigo para tener acceso a las instrucciones de lo que está tratando de hacer (o al menos lo suficientemente cerca como para adaptarse).

Estas instrucciones son cortesía de alguien que decidió documentar lo que estaba haciendo, un colaborador de código abierto que documenta parte de su proyecto o el trabajo profesional de un redactor técnico.

La mayoría de los artículos de "instrucciones" incluirán información sobre la historia detrás del artículo o el objetivo final, lo que ayudará al lector a poner las instrucciones en contexto. Además, la mayoría de los procedimientos incluirán no solo los comandos y los cambios de configuración que deberá realizar para completar la tarea, sino también capturas de pantalla de la salida de los comandos para que pueda comparar sus resultados en diferentes etapas.

Y al final de realizar las tareas descritas en el manual del usuario, debe tener las habilidades básicas que conducen al éxito de la tarea (o lo suficientemente cerca). En este caso, el objetivo final es que puedas armar un manual básico.

Índice

    La introducción

    Incluso esta publicación de blog tenía información introductoria sobre por qué alguien crearía una publicación de instrucciones, e incluso proporcionó información adicional sobre quién podría haberla escrito. La introducción te dio suficiente información para determinar si el artículo era o no lo que estabas buscando.

    Es importante tener en cuenta que es posible que encuentre un manual de instrucciones que no sea 100% adecuado para su escenario, pero está cerca. En este punto, debe tener una idea de las diferencias que puede encontrar y que necesita resolver por su cuenta.

    Instrucciones claras

    La mayoría de la gente aprende de adelante hacia atrás, en una progresión lineal de principio a fin, sin entrar en el esquema de las cosas.

    Una forma de hacer esto es usar encabezados, que en muchos formatos relacionados con Markdown comienzan con una serie de #. Entonces, en el caso de esta sección, el encabezado es en realidad ## Clear Instructions, si tuvieras que mirar el código. Si tuviera que usar algo como un procesador de texto, podría usar texto más grande (markdown no tiene esta característica) y/o audaz texto.

    Otra forma de hacer esto es usar listas numeradas o con viñetas. Por ejemplo:

    1. La introducción

      Contenido

    2. Instrucciones claras

      Contenido

    3. El resto de este artículo

      Contenido

    Donde

    • La introducción

      Contenido

    • Instrucciones claras

      Contenido

    • El resto de este artículo

      Contenido

    ¡Use una combinación de encabezados y listas para que su información sea clara y fácil de seguir!

    codificado

    Cuando se habla de comandos para usar en la interfaz de línea de comandos (CLI) o código en scripts, es importante distinguir esta información de cualquier texto. Ahora, el punto, por supuesto, es que el lector lea su texto y realmente sepa por qué está a punto de escribir el comando y qué va a pasar, pero, como todos sabemos, a veces simplemente hacemos una copia de lo que se nos dice que lo hagamos.

    Entonces, para obtener tanto la distinción como la capacidad de cortar y pegar, puede usar bloques de código en un lenguaje de rebajas.

    Ejemplo

    Para crear un nuevo directorio, necesitará usar el mkdir comando, que significa "hacer directorio". Así que sigamos adelante y creemos un nuevo directorio llamado "prueba".

    mkdir test
    

    Como puede ver, se le ha dado una introducción que explica el propósito, el comando que utilizará y alguna información adicional al respecto, y luego, finalmente, el comando que puede escribir o cortar y pegar. Tenga en cuenta cómo Markdown puede ponerlo en un bloque de código al tener líneas de inicio y fin que contienen ``` y el comando en la línea central o, si es necesario, en varias líneas.

    Visuales

    Las imágenes se pueden utilizar de diferentes maneras. Podría ser un bloque de código que muestre cómo se verían los resultados finales, o podría ser una imagen o un gráfico para ayudar a transmitir la información. El uso de capturas de pantalla de una interfaz puede ser especialmente importante cuando necesita mostrar explícitamente dónde debe hacer clic para completar una tarea o el resultado final de una tarea.

    En el caso de demostrar la salida de un comando, volvamos a nuestro ejemplo anterior y construyamos sobre él.

    Ejemplo

    Para crear un nuevo directorio, necesitará usar el mkdir comando, que significa "hacer directorio". Así que sigamos adelante y creemos un nuevo directorio llamado "prueba".

    # mkdir test
    

    Para ver los resultados de nuestro pedido, escribimos ls para una lista de temas con el -L opción para ver la lista larga.

    # ls -l
    # total 0
    drwxrwxr-x. 2 amy amy 6 Aug  9 18:24 test
    

    En el caso de una interfaz, una captura de pantalla suele ser útil para explicar dónde necesitaría interactuar con ella o para dar una explicación visual.

    Ejemplo

    Para crear una nueva red virtual utilizando la interfaz web, deberá hacer clic en el botón Crear una red virtual en la esquina superior derecha, como se muestra aquí en rojo.

    Esto abrirá una ventana emergente que deberá configurar con la siguiente información para crear nuestro prueba red virtual en el 192.168.100.0/24 red:

    1. Nombre — Nombre de su red (que será "prueba")
    2. Modo de transferencia: por defecto al NAT deseado
    3. Dispositivo: permitiremos que se configure automáticamente.
    4. Configuración de IP: en este caso desea seleccionar solo IPv4.
    5. Red IPv4: en este caso usaremos 192.168.100.0.
    6. Máscara o prefijo — Ya que estamos usando el conjunto / 24, pondremos 24.
    7. Establecer rango de DHCP: no estableceremos un rango de DHCP, así que deje esta opción sin marcar.

    Entonces, en este caso, teníamos una imagen para mostrar la pantalla, con un cuadro para resaltar la parte de la pantalla en la que dijimos que teníamos que hacer clic. Y seguimos eso con el resultado, así como lo que había allí y las opciones que usaremos para completar la tarea.

    Conclusión

    Con cualquier instrucción de uso, debe Conclusión con lo que se debe dejar al lector. Entonces, en este caso, el lector debe obtener una comprensión básica de cómo crear un manual y los tipos de información que debe colocar en él.

    Artículos de interés

    Subir