Informació Nova eina per crear documents a la comunitat

[Viper]

Per tal de potenciar la documentació dels diferents grups amb manuals i tutorials, permetent una elaboració rapida, fàcil i amb l'ajuda de tots, s'ha creat un nou sistema de documentació per la comunitat.

A partir d'ara, els manuals que editeu els podreu pujar als vostres dominis de documentació.

Per l'Arma: arma.cavallersdelcel.cat
Per al DCS: dcs.cavallersdelcel.cat
Per a l'SC: sc.cavallersdelcel.cat

Per preparar els documents abans de pujar-los als vostres dominis, podreu fer servir ara el Github dels Cavallers.
Cada grup te el seu propi apartat del Github.

Per l'Arma: https://github.com/CavallersDelCel/1RA_docs
Per al DCS: https://github.com/CavallersDelCel/DCS_docs
Per a l'SC: https://github.com/CavallersDelCel/SC_docs

Com funciona el domini de documentació?

La web està basada en mkdocs-materials, que fa servir Python i Markdown. És un sistema que evita els errors de format quan es crea el document, ja que el format és molt més simple que el dels editors comuns (MS Word, LlibreOffice...) i per tant fa molt difícil que quan varis usuaris treballin en el mateix document surtin acabats diferents.

Perquè m'entengueu, aquí per posar negretes es fa com a Whatsapp o Discord, es fan servir asteriscos. Així si escric **Cavaller** al document, al web o veurem com Cavaller.
Com que les opcions de format són molt més reduïdes que amb editors com MS Word, editar documents es fàcil i ràpid.

A més, gràcies al Github, podeu treballar en un mateix document varies persones. Cada canvi que fa un company s'avisa a la resta que hi treballa i mostra amb colors les coses que s'han canviat, per si algú veu cap error. I com guarda les versions, sempre es pot retornar a una versió anterior del document.

Com podem començar a editar?

Si sabeu com funciona el Github i com va el Markdown, ho podeu fer ja mateix. Si no, no us preocupeu, vull crear un document d'ajuda perquè entengueu com funciona tot, i podem quedar un dia i us explico com va tot. Veureu lo fàcil i simple que és.

En qualsevol cas, aquestes webs us pode ajudar a tots.

mkdocs-material - https://squidfunk.github.io/mkdocs-material
mkdocs - http://www.mkdocs.org/
Guia rapida del Github - https://goo.gl/9AAAt6
Programa instal·lable per editar en Markdown - http://markdownpad.com
Generador de taules - https://www.tablesgenerator.com/markdown_tables
Github per windows - https://desktop.github.com/
Commonmark - http://commonmark.org
Tutorial Markdown - https://www.markdowntutorial.com

 

[Viper]

Com crear documents?

Per crear documents pel vostre grup l'únic que cal és un compte a Github, res més. El propi Github permet editar documents de forma molt simple, i us dona una vista prèvia simplificada de l'aspecte final.

Si voleu fer servir altres editors també es possible, ja que ofereixen algunes funcions que poden ser interessants.

Si voleu passar de tot això i veure el vídeo resum de com funciona, aneu al final del fil.

Que és Github?

No us explicaré el funcionament complet de Github, ja que pot arribar a ser molt complex, i pel que nosaltres volem no ens cal. En canvi us explicaré les 4 coses bàsiques que heu de saber.

Github és una plataforma per allotjar projectes col·laboratius amb el sistema de control de versions Git. Com a explicació molt simple, vol dir que es poden crear documents i tots els canvis, per petits que siguin, queden registrats, es poden revisar, corregir o eliminar, i fins i tot es pot retornar a una versió anterior del document.

Per profans, això vol dir que si jo pujo un document que es diu formula1.txt amb la frase "Per convertir el plom en or calen llàgrimes d'unicorn", un company si vol pot modificar aquell fitxer, i per exemple posar "Per convertir el plom en or cal caca de nimfa". Llavors aquesta modificació es notificarà a tothom que treballa en el projecte, ens indicara amb color que text s'ha eliminat i quin s'ha inclòs. Si volem li podem corregir a ell la seva aportació, podem descartar-la. O si després de moltes modificacions, volem tornar a una versió antiga del document, també ho podem fer.

Sobre aquest principi tan simple, hi han tot un seguit d'eines i opcions que es poden fer servir (o no). Bàsicament el Github ens permet que diferents persones treballem sobre un mateix document, sense por a cagar-la, perquè tot es notifica, tot es pot revisar, i sempre es pot tornar a una versió anterior.

Com crear compte a Github?

Per crear un compte aneu a https://github.com i ompliu el petit formulari amb les dades que vulgueu.

Com fer servir Github?

Tot i que les possibilitats de Github son extenses, nosaltres només ens centrarem en el bàsic per nosaltres. El principal que heu de saber és:

• Github treballa amb repositoris. Un repositori vol dir un projecte, més o menys. És el total de fitxers que formen un projecte qualsevol.
• Hi han dues maneres de modificar contingut.
  1. Pots modificar el repositori original. Es a dir, si l'ha creat una altre persona, pots modificar directament els seus fitxers.
  2. Pots fer una copia del repositori original de l'altre persona (Es coneix com a Fork), llavors modifiques la teva copia, i un cop has acabat presentes la teva proposició de canvi al repositori original (Es coneix com a Pull Request)
• Cada repositori pot tenir una o mes branques. Si te una normalment sol ser la "master". Si te mes branques, es poden dir com vulguem. Pots tenir la "master", que seria la versió oficial, i la "desenvolupament" que seria on proves les modificacions abans de ficar-les a la master. Però no cal fer servir branques si no es vol.
• El github permet tenir una copia local al teu ordinador del repositori. Així si vols, pots fer les modificacions al teu ordinador i després pujar-les al repositori online.

Aquestes son les característiques principals que us interessen. Ara us posaré un exemple gràfics perquè entengueu millor això.

Vídeotutorial creat per mi perquè veieu com fer servir tot això, i com de cutre queden els vídeos quan no els edito!

Enllaços d'ajuda

Web oficial de la plantilla mkdocs-material - https://squidfunk.github.io/mkdocs-material
Web oficial del sistema mkdocs - http://www.mkdocs.org/
Programa instal·lable per editar en Markdown - http://markdownpad.com
Generador de taules - https://www.tablesgenerator.com/markdown_tables
Tutorial Markdown - https://www.markdowntutorial.com
Guia rapida del Github - https://goo.gl/9AAAt6
Commonmark - http://commonmark.org