Introducción al Technical Writing
¿Qué es Technical Writing? Lleva tu documentación al siguiente nivel
Habilidades para convertirte en Technical Writer
¿Conoces a tu público? Escribe específicamente para tu audiencia
Cómo entrevistar equipos de programación para recolectar información técnica
Estructura gramatical
Un repaso por la gramática básica
Voz activa vs. voz pasiva: estándares y estructura de una oración
Uso correcto de acrónimos y abreviaturas para explicar términos desconocidos
Técnicas de escritura fundamentales para documentos técnicos
Sigue las reglas de George Orwell para escribir con claridad
Uso correcto de listas y tablas para ordenar información
Tipos de párrafos y paso a paso para estructurarlos
Conceptos básicos de programación e ingeniería de software
¿Qué es programación? Evolución de la documentación y technical writing
Lenguajes de programación, tipos de datos y estructura de documentos HTML
Estándares de documentación de código
Cómo documentar una función de código
Buenas prácticas de legibilidad para código y comentarios
Organización y revisión de tu documentación
Organiza y define el alcance de tus documentos
Utiliza Markdown en documentos técnicos
Guía para revisar documentación en equipo de manera efectiva
Cómo organizar documentos largos
Diseño de documentos
Crea ilustraciones instructivas
Conclusiones
Siguientes pasos para convertirte en Technical Writer profesional
Organiza y define el alcance de tus documentos
15/20Lectura
Ya sabes escribir frases coherentes, puedes escribir párrafos claros y precisos. Ahora vamos a aprender a organizar todos esos párrafos en un documento coherente. Así que… here we go!
Define el alcance de tu documento 📏
Un buen documento comienza por definir su alcance. Por ejemplo:
Este documento describe cómo crear apps para Android utilizando la API del marco de trabajo de Android y otras bibliotecas de código abierto.
Estas definiciones de alcance benefician tanto al lector como al technical writer. Puede suceder que, mientras escribes, el contenido de tu documento se aleje de la definición del alcance. Lo que debes de hacer es reenfocar el documento al alcance definido o modificar la definición del alcance.
De cualquier manera, al revisar tu primer borrador puedes eliminar (o pasar a otro documento) cualquier sección que no ayude a satisfacer el alcance del documento.
Define a tu audiencia 👩👩👧👦
Un buen documento especifica explícitamente su audiencia y cualquier conocimiento o experiencia previa. Por ejemplo:
Esta documentación está dirigida para los desarrolladores familiarizados con la programación en JavaScript y conocimientos de programación orientada a objetos.
Establece los puntos clave por adelantado ✊
Nuestros lectores son personas ocupadas que no necesariamente leerán todas las páginas de nuestro documento. Imagina que solo pueden leer el primer párrafo de la página uno. Al revisar tu documentación asegúrate de que el inicio de tu documento responda a las preguntas esenciales de tus lectores.
Los escritores profesionales concentran una energía considerable en la página uno para aumentar las probabilidades de que los lectores lleguen a la página dos. Sin embargo, la página uno de cualquier documento largo es la más difícil de escribir. Prepárate para revisar la página uno muchas veces.
Siempre escribe un resumen ejecutivo (también conocido como abstract) para los documentos largos. Aunque el resumen ejecutivo debe ser muy corto, toma en cuenta que pasarás mucho tiempo escribiéndolo. Un resumen ejecutivo aburrido o confuso es una señal que advierte a los potenciales lectores de que se mantengan alejados.
Cómo escribir para tu audiencia 🚀
A lo largo de este curso he enfatizado varias veces la importancia de definir tu audiencia. En esta sección nos centramos en la definición de la audiencia como un medio para organizar tu documento.
Preguntas para definir a tu audiencia ❓
Responder a las siguientes preguntas te ayudará a determinar qué debe contener tu documento:
- ¿Quién es tu público objetivo?
- ¿Qué es lo que tus lectores ya saben antes de haber leído el documento?
- ¿Qué deberían saber o poder hacer tus lectores después de haber leído el documento?
Por ejemplo, supongamos que en una organización implementarán un nuevo algoritmo de redes neuronales profundas en un programa. La siguiente lista contiene algunas respuestas potenciales a las preguntas anteriores:
- Mi público objetivo está formado por científicas de datos y programadores de mi organización.
- La mayoría de mi público objetivo estudió conceptos avanzados de programación, conoce la API de Keras y tienen conocimiento intermedio en Python. Sin embargo, alrededor del 25% de mi público objetivo no ha implementado un algoritmo de redes neuronales profundas directamente en un programa.
- Después de leer este documento:
- Los lectores tendrán una idea clara de los conceptos teóricos implicados en el desarrollo de software inteligente mediante el uso de redes neuronales profundas.
- Los lectores conocerán el alcance y las mejores prácticas en el desarrollo de sistemas predictivos usando el paradigma de aprendizaje profundo, así como los beneficios implicados en su desarrollo.
- Los lectores serán capaces de desarrollar soluciones para problemas de alta complejidad mediante el diseño, construcción, validación e implementación de modelos de redes neuronales de alto desempeño.
Cómo organizar la estructura de tu documento 🏗
Después de definir tu público, organiza el documento para proporcionar lo que los lectores deben saber o ser capaces de hacer después de leer el documento. Por ejemplo, el esquema del documento podría ser el siguiente:
- Introducción a la Inteligencia Artificial y al Aprendizaje Profundo
1.1. Entendiendo las Redes Neuronales y el Aprendizaje Profundo.
1.2. Desarrollo de Redes Neuronales en Python. - Fundamentos de Aprendizaje de Máquina
2.1. Ramas de Aprendizaje de Máquina.
2.2. Librerías para Aprendizaje de Máquina en Python. - Variantes de Redes Neuronales
3.1. Variantes de Redes Neuronales y sus Fundamentos.
3.2. Arquitectura de una Red Neuronal de Visión Artificial. - Ejemplos de Aplicaciones Modernas usando Aprendizaje Profundo
4.1. Generación de Textos Usando Redes Neuronales Recurrentes.
4.2. Modelos de redes neuronales para generar datos.
Además, ten en cuenta la segmentación de tu público para darle un enfoque correcto a tu documento. Por ejemplo, el público objetivo estudió Python, pero aproximadamente una cuarta parte de tu público podría no recordar los detalles de la API de Keras. Por lo tanto, es probable que en el documento insertes referencias a documentación externa de la API en lugar de intentar explicarla.
Documentación modular: divide tu tema en secciones 🔪
La programación modular se divide en archivos, clases y métodos. El código modular es más fácil de leer, entender, mantener y reutilizar. Hacer que nuestros documentos sean modulares nos da los mismos beneficios. Si eres programador, probablemente tengas una fuerte familiarización con la modularidad funcional en el código, pero ¿cómo usarías estos principios en tu escritura?
Imagina que tienes una bodega vacía en la que necesitas guardar un lote de cajas grandes, medianas y pequeñas. ¿Cómo planearías meter las cajas para asegurarte de que todas podrán entrar en la bodega? Por supuesto que primero meterías las cajas grandes, luego las medianas y finalmente las pequeñas. Si intentaras hacer esto en el orden contrario, fallarás.
La cabeza del lector se parece mucho a una bodega vacía. La información generalmente se acomoda en su cerebro en tres tamaños: grande, mediana y pequeña. Los tamaños de la caja son el tamaño de la información. Necesitas acomodar cada caja dentro del espacio de la cabeza de nuestro lector para que procese y entienda nuestros escritos.
Para decidir el orden de esta información y saber el orden en que debemos de escribirla puedes usar la estrategia de grabarte a ti mismo hablando (o escribiendo libremente) sobre algún tema durante un corto período de tiempo, pueden ser 2 a 5 minutos. Sé específico en tu explicación. Inténtalo varias veces hasta que seas capaz de entenderte a ti mismo y te parezca coherente.
Lo sé, esto requiere disciplina, pero es una herramienta infalible para comunicar la información de manera modular.
¿Pondrás en práctica estos ejercicios? 🔥
Antes de avanzar a la siguiente clase debes completar los siguientes 2 desafíos.
1️⃣ Escribe una documentación para principiantes sobre cómo conectar un celular vía USB a tu computadora.
2️⃣ Escribe la documentación de un programa o función que hayas escrito por tu propia cuenta (en cualquier lenguaje de programación). Imagina que quieres convertir tu proyecto en open-source y estás escribiendo esta documentación para que otras programadoras entiendan tu programa y puedan ayudarte a escalarlo.
Recuerda poner en práctica lo que aprendiste en esta clase. Debes definir el alcance, audiencia y puntos clave de tus documentos.
¡Cuéntame en la sección de comentarios cómo te fue! En la siguiente clase aprenderemos cómo utilizar Markdown para escribir nuestra documentación. ✍
Aportes 16
Preguntas 0
Ordenar por:
¿Cómo conectar tu celular a tu pc con el cable USB?
Esta explicación puede ser usada por cualquier persona sin habilidades técnicas y describe cómo conectar un celular a una pc con el cable USB.
Pasos:
-
Identifica en el cable USB los dos extremos.
-
Sin forzar la conexión conecta el extremo más grande (USB tipo A) en tu computadora.
<Foto>
-
Conecta el otro extremo del cable USB en la ranura de tu celular que corresponda con la forma de la conexión, igualmente sin forzar.
-
Verifica en la pantalla de tu celular si se conectó correctamente a la computadora.
-
En tu celular debería salir en pantalla los permisos y el tipo de conexión que quieras establecer entre el celular y la computadora.
Documentación de código
Va sin acentos para evitar rollos y coloqué sólo la documentación de una clase porque el código es muy largo.
class Borracho:
"""
Es una clase que representa a un hombre que camina random (borracho)
Atributos:
init_position : list
Es un par ordenado de la forma [x,y] que representa la posición inicial
position : list
Es un par ordenado de la forma [x,y] que representa la posición actual del borracho
collide : int
Es la cantidad de choques que ha tenido el borracho
board : Board
Es un objeto de clase Board que representa en qué mundo se mueve este borracho
Metodos:
clearcollide()
Hace que el atributo collide sea 0
clearposition()
Hace que el borracho vuelva a su posicion inicial
dist()
Calcula la distancia euclidiana recorrida por el borracho
move()
Hace que el borracho se mueva de forma random por el board
"""
def __init__(self,position,board):
""" Parametros
position : list
Es un par ordenado de la forma [x,y] que representa la posición inicial
board : Board
Es un objeto de clase Board que representa en qué mundo se mueve este borracho
"""
self.init_position=position
self.position=position
self.collide=0
self.board=board
def clearcollide(self):
""" Hace que el atributo collide sea 0 """
self.collide=0
def clearposition(self):
""" Hace que el borracho vuelva a su posicion inicial """
self.position=self.init_position
def dist(self):
""" Calcula la distancia euclidiana recorrida por el borracho
Return
float
"""
x = self.init_position[0] - self.position[0]
y = self.init_position[1] - self.position[1]
return ((x**2)+(y**2))**0.5
def move(self):
""" Hace que el borracho se mueva de forma random por el board """
myrandom = random.choice(["left","right","up","down"])
if myrandom == "left":
if self.position[0]==0:
self.collide+=1
else:
if self.board.crush(self.position[0]-1,self.position[1]):
self.collide+=1
else:
self.position[0]-=1
elif myrandom == "right":
if self.position[0]==len(self.board)-1:
self.collide+=1
else:
if self.board.crush(self.position[0]+1,self.position[1]):
self.collide+=1
else:
self.position[0]+=1
elif myrandom == "up":
if self.position[1]==len(self.board)-1:
self.collide+=1
else:
if self.board.crush(self.position[0],self.position[1]+1):
self.collide+=1
else:
self.position[1]+=1
elif myrandom == "down":
if self.position[1]==0:
self.collide+=1
else:
if self.board.crush(self.position[0],self.position[1]-1):
self.collide+=1
else:
self.position[1]-=1
Ejercicio 1
Ejercicio 2
<!DOCTYPE html>
<html>
<head>
<title>Numero Mayor condicional</title>
</head>
<body>
<center>
<script type=“text/javascript”>
/**
* [Determinar mayor de 2 numero]
* @param {[var ]} numero01 [Numero uno a comparar]
* @param {[var ]} numero02 [Numero dos a comparar]
* @param {[int]} numero01 [Numero uno a comparar casteado entero]
* @param {[int]} numero02 [Numero dos a comparar casteado a entero]
*/
var numero01;
var numero02;
numero01=parseInt(prompt(“Ingrese el numero 1”,""));
numero02=parseInt(prompt(“Ingrese el numero 2”,""));
if(numero01 >= numero02)
{
//imprime numero mayor
document.write(“El numero mayor es: " + numero01 + " ( Numero 1 )”);
}
else
{
//imprime numero mayor
document.write(“El Numero mayor es : " + numero02 + " ( Numero 2 )”);
}
</script>
</center>
</body>
</html>```
Ejercicio de documentación
Como conectar un teléfono celular a un computador.
En este documento podrás encontrar de manera fácil y sencilla como realzar la conexión de un celular a un computador, no se necesita experiencia solo siguiendo estos pasos se lograra realizar una conexión exitosa.
-
En primer lugar, se debe tener a disposición un cable con conexión usb desde el portátil y una entrada tipo C desde el celular (Preferiblemente el cable con el que se carga el celular)
-
Después se verifica que el computador y el teléfono se encuentren encendidos
-
Se procede a realizar la conexión donde la punta del cable USB será conectada al portátil como se muestra en la imagen
-
El siguiente paso será conectar la punta de conexión tipo C al celular, como se ve a continuación
-
Cuando se realiza este procedimiento se puede recibir en el celular la opción con la cual se procederá a trabajar la conexión desde el teléfono al computar, ya sea compartir datos, cargar el teléfono o revisar carpetas multimedia, también por parte del pc se mostrara un mensaje que reconoce el teléfono y que la conexión USB es exitosa.
Palindromo
La presente documentación va dirigido a personas que tienen conocimientos básicos del lenguaje de programación Python y funciones lambda.
Un palindromo es una palabra que, sin importar como se lea (bien sea de derecha a izquierda, como de izquierda a derecha) va a significar lo mismo:
Ejemplo:
- ana,
- solos.
En el siguiente código se ingresa como parámetro el texto solos con el objetivo de que si la palabra es un Palindromo, ésta devuelve True, de lo contrario devulve un False
def run():
palindrome = lambda string: string == string[::-1]
print(palindrome('solos'))
if __name__ == '__main__':
run()
Para conocer más a detalle este ejercicio, te invito a que veas la clase de funciones anónimas con el Master Facundo 😉
¿Cómo conectar tu celular con una pc vía USB?
Este documento está dirigido a personas con poca o ninguna experiencia en el campo de la tecnología.
Requisitos:
- Debes tener un computador conectado a la toma eléctrica y/o con batería cargada (este procedimiento funciona tanto para computadores portátiles como con los computadores de escritorio); para el ejercicio no vamos a tener en cuenta el sistema operativo del pc.
- Debes tener un celular con su respectivo cable que viene de fábrica cuando realizas la compra del mismo. (Se recomienda el cable de fábrica, ya que existen diferentes tecnologías de cables con diferentes formas en sus extremos, los conectores).
Cumpliendo los requisitos descritos anteriormente, vamos a continuar con los siguientes pasos para alcanzar nuestro objetivo:
- Conecta el extremo más pequeño del cable al celular en su respectiva ranura.
- Conecta el otro extremo del cable al computador (verifica la forma de la ranura, ya que existen ranuras parecidas).
En tu computador debe aparecer un nuevo cuadro (ventana) que nos confirma que se conectó el celular correctamente al computador y posteriormente te pide unos permisos dependiendo de lo que quieras hacer en éste.
- Cómo conectar un celular vía USB a tu computadora.
Esta guía se describe el procesos de como conectar tu celular a tu computadora y está dirigida a personas que tienen poco conocimiento en la manipulación de dispositivos electrónico.
Debes tener los siguientes requisitos:
-
Un celular.
-
El cable USB del celular.
-
Una computadora.
Para conectar tu celular al computador debe hacer los siguientes pasos:
- Conectar un extremo del cable USB al celular(Donde se coloca a cargar el celular).
- Conectar el otro extremo(TIPO USB) a la entrada del computador que concuerda con el aspecto físico del conector del cable.
- Ir a la configuración del equipo en “Mi equipo” y corroborar que el computador reconozca el celular.
Listo tu celular ya está conectado vía USB a tu computadora.
- Conexión a MySQL usando PHP
/** [Código de como hacer una conexión básica a nuestra base de datos utilizando PHP ]
-
@param {[string} servername [nombre del servidor]
-
@param {[string]} database[nombre de la base de datos]
*@param {[string} user [nombre del usuario administrador de la base de datos]
- @param {[string]} password [Contraseña de la base de datos]
<?php
$servername = “localhost”;
$database = “databasename”;
$username = “username”;
$password = “password”;
// se utiliza la función de php mysquli_connect donde requiere los parametros anteriormente creados.
$conn = mysqli_connect($servername, $username, $password, $database);
// Hacemos una validación para saber si se realizó de manera correcta la conexión
if (!$conn) {
die("Connection failed: " . mysqli_connect_error());
}
echo “Connected successfully”;
mysqli_close($conn);
?>
Comparto mi ejercicio número 2:
/**
* Retorna la suma de los cuadrados de dos números
*
* @param {Number} number1: Primer número a sumar
* @param {Number} number2: Segundo número a sumar
* @return {Number} La suma del primer número elevado al cuadrado más el segundo número elevado al cuadrado.
*/
function sumarCuadrados(number1, number2) {
return (number1 * number1) + (number2 * number2);
}
En este tutorial aprenderás a conectar un teléfono celular a una PC usando un cable USB. De modo que podremos pasar archivos de un dispositivo al otro. Se espera que el lector tenga conocimientos básicos en el manejo de archivos en su PC, ya que, no se profundizara en este tema. A continuación te mostramos un cable USB:
Estos se caracterizan por tener un extremo que se ve de la siguiente manera:
Este conector es llamado USB tipo A macho y la mayor parte de las computadoras tienen una entrada compatible, búscala en la tuya:
Para que la conexión funcione adecuadamente asegúrate de que el otro extremo del cable encaje perfectamente en la entrada de carga de tu dispositivo móvil. En la actualidad existen mayoritariamente dos tipos de conectores:
Una vez ambos extremos estén conectados debería salir en el dispositivo telefónico la siguiente alerta o una parecida:
Presiónala y se podrá elegir en que forma se desea conectar el dispositivo. Como el objetivo de este tutorial es pasar archivos de un dispositivo a otro utilizaras la opción file transfer:
Ya presionada la opción. En la PC debería salir el dispositivo móvil conectado. Búscalo en tu explorador de archivos:
Haciendo clic en el dispositivo podrás navegar por los archivos y carpetas de tu teléfono. Para pasar archivos de un dispositivo a otro solo será cuestión de pegar o cortar archivos de un lugar a otro.
Reto 2
/**
* Inserción de un elemento en la base de datos
* @param database Base de datos con la que estamos trabajando
* @param collection Colección donde deseamos insertar el elemento
* @param document elemento a insertar
*/
export const insertOneElement = async (
database: Db,
collection: string,
document: object
) => {
return await database.collection(collection).insertOne(document);
};
Reto 1
Guía para conectar un iPhone vía USB-C a una computadora Mac.
Esta guía esta pensado para personas que utilizan tanto un iPhone, como también un Mac con sistema operativo OSX o superior.
Requisitos necesarios:
- iPhone con entrada Lighting.
- Cable Lighting a USB-C.
- Mac con un puerto USB-C libre.
Pasos necesarios:
- Conectar el extremo del cable con salida Lighting al iPhone.
- Conectar el otro extremos el cual cuenta con la salida USB-C al ordenador Mac.
- Escribir la contraseña del iPhone para desbloquearlo y confirmar que el Mac al que esta conectado es un dispositivo de confianza.
Comparto mi ejercicio número 1:
<h1>Guía para conectar un teléfono a una computadora vía USB</h1>En esta guía se presentan los pasos para conectar un teléfono celular android a una computadora a través de un cable USB.
La guía está enfocada a cualquier persona que utilice habitualmente un teléfono móvil android y una computadora PC con windows o linux. No se requieren conocimientos avanzados.
Antes de comenzar asegúrese de contar con lo siguiente:
- Un teléfono móvil o tablet con sistema operativo android
- Una computadora con al menos un puerto USB libre y con sistema operativo windows o linux
- Un cable USB
Paso 1: Conecte el lado del cable más pequeño al teléfono
Paso 2: Conecte el lado más grande del cable a la computadora
Paso 3: En las notificaciones del teléfono debe buscar la opción para seleccionar el modo de conexión entre el celular y la computadora. Hay tres posibles opciones
- Cargar solamente
- Transferir archivos
- Transferir fotos (PTP)
- Usar dispositivo como MIDI
Debe seleccionar la segunda opción: Transferir archivos.
Paso 5: Se abrirá una ventana del explorador de archivos desde la cual podrá navegar en el almacenamiento interno de su celular y copiar archivos entre el teléfono y la computadora.
Paso 6: Al finalizar, en las notificaciones, busque el mismo listado del paso 3 y seleccione Cargar solamente. Después de esto ya puede desconectar de manera segura el cable USB.
Reto 1
<h3>Como conectar un celular via USB a tu computadora</h3> <h4>Requisitos</h4>- Celular smartphone con entrada
- Tipo C o
- Tipo OTG
- Cable compatible con tu celular
- Tipo C a USB o
- Tipo OTG a USB
- Computadora con entrada USB
- Prende la computadora
- Verifica que el celular tenga suficiente bateria, de preferencia arriba de 30%
- Conecta la entrada Tipo C o OTG al celular
- Conecta el puerto USB a la computadora
- Revisa que en tu computadora te indique que se encontro dispositivo
Reto 2
/**
* @description : Servicio REST que envia información a pagina web
* @author : [email protected]
* @group : Digital Grow
* @last modified on : 23-01-2021
* @last modified by : [email protected]
* Modifications Log
* Ver Date Author Modification
* 1.0 01-22-2021 [email protected] Initial Version
**/
@RestResource(urlMapping ='/Service_Website')
global with sharing class Service_Website {
@HttpPost
global static void Service_WebsiteLoginPacientesGet() {
// Obtiene el JSON recibido por el servicio POST
RestRequest rest_Request = RestContext.request;
String respuesta_Body = rest_Request.requestBody.toString();
// Convierte Json recibido a Wrapper
Wrapper_PeticionWeb wrp_PeticionWeb = (Wrapper_PeticionWeb) JSON.deserialize(respuesta_Body,Wrapper_PeticionWeb.class);
// Obtiene la información solicitada por servicio POST
SObject resultado = get_InformacionSolicitada(wrp_PeticionWeb);
envia_Resultados(resultado);
}
// Envia respuesta a servicio POST
private static void envia_Resultados(SObject resultado) {
RestResponse respuesta = RestContext.response;
if (respuesta == null) {
respuesta = new RestResponse();
RestContext.response = respuesta;
}
respuesta.responseBody = Blob.valueOf(JSON.serialize(resultado));
}
// Dependiendo los parametros recibidos por el servicio POST obtiene la información a enviar
private static SObject get_InformacionSolicitada(Wrapper_PeticionWeb wrp_PeticionWeb) {
String str_Query = 'SELECT Id, Name FROM '+ wrp_PeticionWeb.objeto +' WHERE id = '+wrp_PeticionWeb.id_Registro;
SObject obj_Dinamico = Database.query(str_Query);
return obj_Dinamico;
}
// Valida que el Json recibido contenga las variables correctas
global class Wrapper_PeticionWeb{
public String id_Registro {get;set;}
public String objeto {get;set;}
}
Comparto mi ejercicio numero 1:
[Guía para conectar teléfono a computadora vía USB]
¿Quieres ver más aportes, preguntas y respuestas de la comunidad? Crea una cuenta o inicia sesión.