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

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

7

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

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

Utiliza Markdown en documentos t茅cnicos

16/20

Lectura

Markdown es un lenguaje de marcado ligero que muchos profesionales utilizan para crear y editar documentos t茅cnicos. Con Markdown escribes el texto en un editor de texto plano insertando caracteres especiales para crear encabezados, negritas, vi帽etas, etc. El texto plano es simplemente el alfabeto normal, con unos cuantos s铆mbolos familiares como asteriscos ( * ) o comillas simples ( ``` ). El siguiente ejemplo muestra una descripci贸n t茅cnica sencilla formateada con Markdown:

Markdown Platzi

El sitio web Markdown Tutorial nos comparte que, a diferencia de las aplicaciones de procesadores de texto, el texto escrito en Markdown puede ser f谩cilmente compartido entre diferentes equipos, dispositivos m贸viles y personas. Y se est谩 convirtiendo r谩pidamente en el est谩ndar para escritos de acad茅micos, cient铆ficos, escritores y muchas m谩s. Ejemplo de ellos son Platzi, GitHub y Reddit, quienes utilizan Markdown para dar formato a sus comentarios.

驴En qu茅 se utiliza Markdown? 馃

De acuerdo con la documentaci贸n de Markdown, este lenguaje de marcado es bueno para:

  • P谩ginas web
  • Contratos
  • Notas
  • Libros
  • Presentaciones
  • Emails
  • Documentaci贸n
  • 隆Y muchos m谩s!

Hoy en d铆a muchos escritores t茅cnicos tienen sus blogs, as铆 que cualquiera puede usar Markdown para sus sitios web y blogs.

Editores de Markdown 馃搵

Para trabajar con Markdown puedes hacerlo desde editores de texto como:

Curso de Prework: Buenas Pr谩cticas y Entorno de Desarrollo

Solo debes crear un archivo con extensi贸n .markdown o .md. Escribe el texto como lo haces habitualmente pero utilizando la sintaxis de Markdown. A continuaci贸n, guarda el archivo y, si tu herramienta admite Markdown, imp贸rtalo.

Si quieres un editor online, te recomiendo:

Solo abre el sitio y empieza a escribir. La mayor铆a de estos editores te muestran dos paneles, uno en donde vas escribiendo y otro en donde se va viendo la adaptaci贸n a Markdown.

Breve introducci贸n a la sintaxis de Markdown 鈸

Dar formato a textos mediante Markdown tiene una curva de aprendizaje suave. Cabe mencionar que Markdown no hace grandes modificaciones como cambiar el tama帽o de la fuente, el color o el tipo. Lo 煤nico sobre lo que se puede trabajar es en c贸mo se muestra el texto, por ejemplo, marcar texto en negrita, crear encabezados u organizar listas de elementos. A continuaci贸n, te dejo algunos formatos b谩sicos de introducci贸n al Markdown:

1. Encabezados

Los encabezados se usan frecuentemente en sitios web, art铆culos de revistas y avisos para llamar la atenci贸n sobre una secci贸n. Como su nombre lo indica, act煤an como t铆tulos o subt铆tulos sobre las secciones.

Hay seis tipos de encabezados en tama帽os decrecientes y se usa el s铆mbolo hash (**#**) para definir el tama帽o del t铆tulo. Si el encabezado es H1, se agrega un hash, si el encabezado es H2, se agregan dos hashes y as铆 sucesivamente hasta llegar al H6.

# H1
## H2
### H3
#### H4
##### H5
###### H6

2. 脡nfasis

Tres b谩sicos elementos en este formato de texto son: it谩lica, negrita y tachada. Para hacer una palabra en it谩lica debes poner un asterisco (*) al inicio y al final de cada palabra. Si quieres el formato negrita, ser谩n dos asteriscos (**) al inicio y al final de la palabra o frase. Y si es formato tachado, entonces ser谩n dos virgulillas (~~) al inicio y final de cada palabra o frase.

*It谩lica*

**Negrita**

~~Tachada~~

It谩lica

Negrita

Tachada

3. Listas

Como te mencion茅 anteriormente, hay varios tipos de listas. Utiliza las listas ordenadas (numeradas) cuando los elementos deban seguir un orden (por ejemplo, instrucciones para cocinar) y las listas desordenadas (con vi帽etas) cuando no importa el orden de las instrucciones (por ejemplo, una lista de mercado).

- Lista desordenada
- Usa este tipo de listas
- Cuando no importe el orden
- De los elementos de la lista

1. Lista ordenada
2. Aqu铆 los elementos
3. De la lista
4. Debes ir en este orden

4. Enlaces

Este tipo de enlace es el llamado enlace en l铆nea. Para crear un enlace en l铆nea debes encerrar el texto del enlace entre corchetes ( [ ] ) y despu茅s encerrar el enlace entre par茅ntesis ( ( ) ).

[Platzi](https://platzi.com/)

Platzi

驴Verdad que es muy sencillo?

Si quieres profundizar, aqu铆 est谩 la Sintaxis B谩sica de Markdown para que te asegures de conocerlo a profundidad. Si lo que quieres es practicar, reserva 20 minutos de tu d铆a a este tutorial de Markdown para aprender toda la sintaxis b谩sica.

Ahora escribe tu documentaci贸n con Markdown 馃憡

Es hora de poner en pr谩ctica todo lo que aprendiste en esta clase. 驴Recuerdas la documentaci贸n que escribiste en la clase anterior? Ahora debes transformarla a Markdown aprovechando todas las funcionalidades y formatos que acabas de aprender. 隆No olvides dejar tu resultado en los comentarios!


Luego de completar el reto te invito a acompa帽arme a la siguiente clase para aprender a revisar nuestro contenido efectivamente.

Aportes 12

Preguntas 0

Ordenar por:

驴Quieres ver m谩s aportes, preguntas y respuestas de la comunidad? Crea una cuenta o inicia sesi贸n.

Toda mi documentaci贸n la hago en Notion 馃枻
Aprender a usar Markdown es muy importante para nosotros los programadores, dado que los archivos README (Archivo de descripci贸n, presentaci贸n y detalles del proyecto) que usamos en GitHub o GitLab usan Markdown.

Recomiendo mucho esta web que sirve tambi茅n como editor y te da una vista previa: https://pandao.github.io/editor.md/en.html

Puedes hacer la documentaci贸n a tu proyecto directamente en GitHub mediante una Wiki, escrib铆 un tutorial sobre esto aqu铆 en Platzi: https://www.notion.so/Documentaci-n-en-GitHub-14c96b7999ce4474a83ec32e448cb5b4

Formato Markdown

# Reto 1

## Como conectar un celular via USB a tu computadora

### Requisitos
1. [Celular smartphone](https://www.whistleout.com.mx/CellPhones/Guides/que-es-un-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

### Pasos para conectar
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

### Glosario
- Como es una entrada Tipo C a USB presiona [AQUI](https://www.google.com/search?q=entrada+tipo+c+a+usb&sxsrf=ALeKk02Nt4BOMbvQ1qLe1uHiG6ya0lYDiQ:1611465557441&source=lnms&tbm=isch&sa=X&ved=2ahUKEwjzuPmA6bPuAhVGPawKHYvZCUkQ_AUoAXoECAQQAw&biw=1536&bih=754&dpr=1.25)
- Como es una entrada Tipo OTG a USB presiona [AQUI](https://www.google.com/search?q=entrada+tipo+otg+a+usb&tbm=isch&ved=2ahUKEwi2hpyC6bPuAhUOXawKHWuOA4IQ2-cCegQIABAA&oq=entrada+tipo+otg+a+usb&gs_lcp=CgNpbWcQAzoGCAAQBxAeOggIABAHEAUQHjoGCAAQCBAeUKOYBljsnwZguKMGaABwAHgAgAFUiAGrApIBATSYAQCgAQGqAQtnd3Mtd2l6LWltZ8ABAQ&sclient=img&ei=WAMNYLb6BY66sQXrnI6QCA&bih=754&biw=1536)



# Reto 2
/**
 * @description       : Servicio REST que envia informaci贸n a pagina web
 * @author            : erika.villanueva@salauno.com.mx
 * @group             : Digital Grow
 * @last modified on  : 23-01-2021 
 * @last modified by  : erika.villanueva@salauno.com.mx
 * Modifications Log
 * Ver   Date         Author                               Modification
 * 1.0   01-22-2021   erika.villanueva@salauno.com.mx   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;}
    }

En la clase anterior usamos markdown porque tambi茅n es lo que se usa para los comentarios en platzi, sin embargo dejo por aqu铆 otros proyecticos que hice en markdown: Shortcuts en vscode y Tu primer repositorio - Github B谩sico

Con Markdown tambi茅n pueden poner videos de YouTube鈥 馃憖
.

El ejercicio anterior con formato markdown (hice trampa porque us茅 notion para esto)

# Gu铆a para conectar un tel茅fono a una computadora v铆a USB

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 como el que se muestra a continuaci贸n

[https://external-content.duckduckgo.com/iu/?u=https%3A%2F%2Ftse1.mm.bing.net%2Fth%3Fid%3DOIP.IzTNPwbOt7vVZ-yahNp9IwHaHa%26pid%3DApi&f=1](https://external-content.duckduckgo.com/iu/?u=https%3A%2F%2Ftse1.mm.bing.net%2Fth%3Fid%3DOIP.IzTNPwbOt7vVZ-yahNp9IwHaHa%26pid%3DApi&f=1)

**Paso 1**: Conecte el lado del cable ms peque帽o al tel茅fono

[https://external-content.duckduckgo.com/iu/?u=https%3A%2F%2Ftse1.mm.bing.net%2Fth%3Fid%3DOIP.fpH_TMV7tCX2TaeVnOs2yAHaDU%26pid%3DApi&f=1](https://external-content.duckduckgo.com/iu/?u=https%3A%2F%2Ftse1.mm.bing.net%2Fth%3Fid%3DOIP.fpH_TMV7tCX2TaeVnOs2yAHaDU%26pid%3DApi&f=1)

**Paso 2**: Conecte el lado ms grande del cable a la computadora

[https://external-content.duckduckgo.com/iu/?u=https%3A%2F%2Ftse1.mm.bing.net%2Fth%3Fid%3DOIP.1N8BAuMB1H-2_TECdt8UIQAAAA%26pid%3DApi&f=1](https://external-content.duckduckgo.com/iu/?u=https%3A%2F%2Ftse1.mm.bing.net%2Fth%3Fid%3DOIP.1N8BAuMB1H-2_TECdt8UIQAAAA%26pid%3DApi&f=1)

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

[https://external-content.duckduckgo.com/iu/?u=https%3A%2F%2Ftse2.mm.bing.net%2Fth%3Fid%3DOIP.GRYbkIB-K87FQZENuSEWMgAAAA%26pid%3DApi&f=1](https://external-content.duckduckgo.com/iu/?u=https%3A%2F%2Ftse2.mm.bing.net%2Fth%3Fid%3DOIP.GRYbkIB-K87FQZENuSEWMgAAAA%26pid%3DApi&f=1)

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

Conecta un celular a una PC usando un cable USB

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.

Gu铆a para conectar un celular v铆a USB a una computadora

Este documento describe c贸mo conectar un celular v铆a USB a una computadora.

Esta gu铆a est谩 dirigida para personas sin experiencia t茅cnica, que cuentan con un celular y una computadora con conexi贸n USB.

Antes de proceder a ejecutar los pasos descriptos en esta gu铆a debe asegurarse tener un cable USB con sus extremos de diferente tama帽o.

Pasos a seguir.

  1. Identificar el puerto USB en su computadora.

  2. Colocar el extremo m谩s grande del cable USB en el puerto recientemente identificado.

  3. Identificar el puerto de entrada en su tel茅fono.

  4. Colocar el extremo m谩s peque帽o del cable USB en el puerto identificado previamente.

C贸mo conectar un celular v铆a USB a tu computadora.

<h3>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.</h3> <h4>Debes tener los siguientes requisitos:</h4>
  • 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.

<h1>Encabezados</h1> <h1>脡nfasis</h1>

Realizando prueba con It谩lica
Realizando prueba con Negrita
Realizando prueba con Tachada

<h1>Listas</h1>
  • Realizando prueba con It谩lica
  • Realizando prueba con Negrita
  • Realizando prueba con Tachada
<h1>Enlaces</h1>

Link busquedas Goolge

Yo uso Notion, lo recomiendo para Databases y es bueno para tomar apuntes y hacer documentacion!

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.

<h3>Requisitos necesarios:</h3>

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

<h3>Pasos necesarios:</h3>

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.