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
Lectura
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!
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.
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.
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.
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.
Responder a las siguientes preguntas te ayudará a determinar qué debe contener tu 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:
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:
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.
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.
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
¿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.
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:
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 😉
Este documento está dirigido a personas con poca o ninguna experiencia en el campo de la tecnología.
Requisitos:
Cumpliendo los requisitos descritos anteriormente, vamos a continuar con los siguientes pasos para alcanzar nuestro objetivo:
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.
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:
Listo tu celular ya está conectado vía USB a tu computadora.
@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]
<?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:
Pasos necesarios:
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:
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
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.
/**
* @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.