Introducci贸n al Technical Writing

1

驴Qu茅 es Technical Writing? Lleva tu documentaci贸n al siguiente nivel

2

Habilidades para convertirte en Technical Writer

3

驴Conoces a tu p煤blico? Escribe espec铆ficamente para tu audiencia

4

C贸mo entrevistar equipos de programaci贸n para recolectar informaci贸n t茅cnica

Estructura gramatical

5

Un repaso por la gram谩tica b谩sica

6

Uso correcto de acr贸nimos y abreviaturas para explicar t茅rminos desconocidos

7

Voz activa vs. voz pasiva: est谩ndares y estructura de una oraci贸n

T茅cnicas de escritura fundamentales para documentos t茅cnicos

8

Sigue las reglas de George Orwell para escribir con claridad

9

Uso correcto de listas y tablas para ordenar informaci贸n

10

Tipos de p谩rrafos y paso a paso para estructurarlos

Conceptos b谩sicos de programaci贸n e ingenier铆a de software

11

驴Qu茅 es programaci贸n? Evoluci贸n de la documentaci贸n y technical writing

12

Lenguajes de programaci贸n, tipos de datos y estructura de documentos HTML

Est谩ndares de documentaci贸n de c贸digo

13

C贸mo documentar una funci贸n de c贸digo

14

Buenas pr谩cticas de legibilidad para c贸digo y comentarios

Organizaci贸n y revisi贸n de tu documentaci贸n

15

Organiza y define el alcance de tus documentos

16

Utiliza Markdown en documentos t茅cnicos

17

Gu铆a para revisar documentaci贸n en equipo de manera efectiva

18

C贸mo organizar documentos largos

Dise帽o de documentos

19

Crea ilustraciones instructivas

Conclusiones

20

Siguientes pasos para convertirte en Technical Writer profesional

Organiza y define el alcance de tus documentos

15/20

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!

...

Reg铆strate o inicia sesi贸n para leer el resto del contenido.

Aportes 21

Preguntas 0

Ordenar por:

驴Quieres ver m谩s aportes, preguntas y respuestas de la comunidad?

o inicia sesi贸n.


驴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:

  1. Identifica en el cable USB los dos extremos.

  2. Sin forzar la conexi贸n conecta el extremo m谩s grande (USB tipo A) en tu computadora.

<Foto>

  1. 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.

  2. Verifica en la pantalla de tu celular si se conect贸 correctamente a la computadora.

  3. 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:

Reto 1

<h3>Como conectar un celular via USB a tu computadora</h3> <h4>Requisitos</h4>
  1. Celular smartphone con entrada
    • Tipo C o
    • Tipo OTG
  2. Cable compatible con tu celular
    • Tipo C a USB o
    • Tipo OTG a USB
  3. Computadora con entrada USB
<h4>Pasos para conectar</h4>
  1. Prende la computadora
  2. Verifica que el celular tenga suficiente bateria, de preferencia arriba de 30%
  3. Conecta la entrada Tipo C o OTG al celular
  4. Conecta el puerto USB a la computadora
  5. 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;}
    }

Ejercicio 1

Ejercicio 2

<!DOCTYPE html>
<html>
<head>
<title>Numero Mayor condicional</title>
</head>
<body>
<center>
<script type=鈥渢ext/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(鈥淚ngrese el numero 1鈥,""));
numero02=parseInt(prompt(鈥淚ngrese el numero 2鈥,""));

if(numero01 >= numero02)
{
//imprime numero mayor
document.write(鈥淓l numero mayor es: " + numero01 + " ( Numero 1 )鈥);
}
else
{
//imprime numero mayor
document.write(鈥淓l Numero mayor es : " + numero02 + " ( Numero 2 )鈥);
}
</script>

</center>
</body>
</html>```

Desaf铆o 2: Documentaci贸n de un programa o funci贸n open-source

T铆tulo: Documentaci贸n del proyecto [Nombre del proyecto]

Introducci贸n:
隆Bienvenida al proyecto [Nombre del proyecto]! Esta documentaci贸n tiene como objetivo ayudarte a comprender el funcionamiento de este programa/funcci贸n y c贸mo puedes contribuir a su desarrollo. Si est谩s interesada en participar en el proyecto y contribuir con tus ideas y habilidades, est谩s en el lugar correcto.

脥ndice:

Descripci贸n general

Prop贸sito del proyecto
Funcionalidades principales
Requisitos del sistema
Gu铆a de instalaci贸n

Requisitos previos
Pasos de instalaci贸n
Configuraci贸n inicial
Uso del programa/funcci贸n

Par谩metros de entrada
Salida y resultados esperados
Ejemplos de uso
Arquitectura y dise帽o

Estructura del c贸digo fuente
Explicaci贸n de los componentes principales
Diagramas de flujo o diagramas de clases
Contribuci贸n al proyecto

C贸mo realizar contribuciones
Proceso de solicitud de cambios (Pull Request)
Normas de codificaci贸n y estilo
Informaci贸n adicional

Desaf铆o 1: Documentaci贸n para principiantes sobre c贸mo conectar un celular v铆a USB a tu computadora.

T铆tulo: Gu铆a para conectar un celular v铆a USB a tu computadora

Introducci贸n:
Conectar tu celular a tu computadora mediante un cable USB es una tarea sencilla que te permite transferir archivos, cargar tu dispositivo y realizar diversas acciones de sincronizaci贸n. En esta gu铆a para principiantes, aprender谩s c贸mo conectar tu celular a tu computadora de manera segura y sin complicaciones.

Requisitos previos:

Un celular con cable USB.
Una computadora con un puerto USB disponible.
El cable USB que se ajuste al puerto de tu celular.
Pasos para conectar tu celular v铆a USB a tu computadora:

Encuentra el puerto USB en tu computadora: Busca los puertos USB en tu computadora. Generalmente, se encuentran en los lados o en la parte trasera del dispositivo. Pueden estar etiquetados con el 铆cono de USB.

Conecta un extremo del cable USB a tu celular: Localiza el puerto de carga de tu celular y conecta un extremo del cable USB en 茅l. Aseg煤rate de que el cable encaje correctamente y est茅 firmemente conectado.

Conecta el otro extremo del cable USB a tu computadora: Toma el extremo restante del cable USB y con茅ctalo al puerto USB de tu computadora. Nuevamente, aseg煤rate de que el cable est茅 bien conectado.

Confirma la conexi贸n en tu celular: En tu celular, es posible que se muestre una notificaci贸n o una opci贸n para seleccionar el tipo de conexi贸n USB. Dependiendo de tus necesidades, puedes elegir la opci贸n de 鈥淭ransferencia de archivos鈥 para acceder a los archivos de tu celular desde la computadora.

Accede a tu celular desde la computadora: Una vez que tu celular est茅 conectado y configurado correctamente, podr谩s acceder a 茅l desde tu computadora. Abre el Explorador de archivos en Windows o el Finder en macOS, y ver谩s tu celular como un dispositivo externo. Desde all铆, podr谩s copiar, mover o eliminar archivos seg煤n sea necesario.

Finalizaci贸n y desconexi贸n: Una vez que hayas terminado de usar tu celular con la computadora, es importante desconectarlo de manera segura. En Windows, haz clic derecho en el 铆cono del dispositivo en el Explorador de archivos y selecciona 鈥淓xpulsar鈥 o 鈥淓xtraer hardware de forma segura鈥. En macOS, arrastra el 铆cono del dispositivo a la Papelera para expulsarlo.

El USB, del ingl茅s 鈥淯niversal serial bus鈥 es un protocolo de comunicaciones electr贸nico que suele usarse en accesorios de computadoras y otros accesorios peque帽os.
El USB sirve para el intercambio de datos, el desarrollo de operaciones y, en algunos casos, la carga de la bater铆a del dispositivo o dispositivos conectados.
Para conectarlo de tu celular hacia tu computadora, sigue los pasos a continuaci贸n:
1- Enciende tu computadora y celular
2- Conecta la entrada m谩s peque帽a del cable a la parte trasera de tu tel茅fono y la entrada m谩s ancha a la abertura/puerto de tu CPU o computadora portatil(ver谩s un s铆mbolo de USB en la abertura correspondiente)
3- Si la conexi贸n es efectiva te notificar谩 una ventana en tu pantalla, de lo contrario, chequea en la barra inferior de tu computadora, desplegando los 铆conos ocultos.

EJERCICIO #1:



EJERCICIO #2:
Este generador de contrase帽as es un ejercicio del Curso b谩sico de Python
Repositorio en GitHub

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.

  1. 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)

  2. Despu茅s se verifica que el computador y el tel茅fono se encuentren encendidos

  3. Se procede a realizar la conexi贸n donde la punta del cable USB ser谩 conectada al port谩til como se muestra en la imagen

  4. El siguiente paso ser谩 conectar la punta de conexi贸n tipo C al celular, como se ve a continuaci贸n

  5. 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:

  1. 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.
  2. 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.



  1. 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:

  1. Conectar un extremo del cable USB al celular(Donde se coloca a cargar el celular).
  2. Conectar el otro extremo(TIPO USB) a la entrada del computador que concuerda con el aspecto f铆sico del conector del cable.
  3. Ir a la configuraci贸n del equipo en 鈥淢i equipo鈥 y corroborar que el computador reconozca el celular.

Listo tu celular ya est谩 conectado v铆a USB a tu computadora.

  1. 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 = 鈥渓ocalhost鈥;
$database = 鈥渄atabasename鈥;
$username = 鈥渦sername鈥;
$password = 鈥減assword鈥;
// 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 鈥淐onnected 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:

  1. iPhone con entrada Lighting.
  2. Cable Lighting a USB-C.
  3. Mac con un puerto USB-C libre.

Pasos necesarios:

  1. Conectar el extremo del cable con salida Lighting al iPhone.
  2. Conectar el otro extremos el cual cuenta con la salida USB-C al ordenador Mac.
  3. 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:

  1. Un tel茅fono m贸vil o tablet con sistema operativo android
  2. Una computadora con al menos un puerto USB libre y con sistema operativo windows o linux
  3. 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

  1. Cargar solamente
  2. Transferir archivos
  3. Transferir fotos (PTP)
  4. 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.

Comparto mi ejercicio numero 1:
[Gu铆a para conectar tel茅fono a computadora v铆a USB]