Una de les tasques més important a l'hora de crear programari és la documentació, lamentablement per als que desenvolupem a vegades aquesta tasca ens sembla tediosa, però per a ningú és un secret que una bona documentació pot ser el punt d'èxit de qualsevol eina, ja sigui per l'ajuda que se li brinda als usuaris per entendre el correcte funcionament de l'aplicació o la informació que se li subministra als altres desenvolupadors per millorar-la.
Hi ha aplicacions bastant bones que ens permeten documentar els nostres projectes d'una manera senzilla, algunes tendeixen a oferir més del que realment volem i altres requereixen de complexes instal·lacions, una eina per documentar projectes que compleix i és bastant senzilla d'usar i instal·lar és Docusaurus.
Què és Docusaurus?
Docusaure és un projecte per construir, implementar i mantenir la documentació web d'eines de codi obert, El mateix permet utilitzar el llenguatge Markdown per escriure la documentació que després serà publicada com un lloc web html, de la mateixa manera, l'eina permet estendre i personalitzar el disseny del nostre lloc web de documentació amb l'ús de React.
En línies generals aquesta eina de codi obert desenvolupada per l'equip de programació de Facebook, ens permet crear fàcilment llocs web bonics i lleugers on podem mostrar adequadament la documentació de qualsevol projecte.
L'eina està equipada amb funcionalitats per al correcte versions a dels documents, un avançat cercador, la possibilitat de documentar i redissenyar el nostre lloc de documentació en temps real, integració amb traduccions i moltes altres característiques que l'ajudarà a preocupar menys per documentar o millor dit per fer el procés de documentació més senzill i amb acabat més agradable.
El fàcil ús de Docusaurus es pot comprovar en el següent gif distribuït pels seus desenvolupadors
Com instal·lar Docusaurus?
Docusaurus té com a objectiu principal ser l'eina definitiva per documentar aplicacions de codi obert allotjades a github, per la qual cosa és realment senzill poder instal·lar i fer caminar teu lloc web de documentació en aquesta plataforma.
Per començar a gaudir Docusaurus en Github n'hi ha prou amb seguir els passos indicats per l'equip de desenvolupament i que citem a continuació:
- Aneu a l'arrel del seu directori de repositori de GitHub on crearà els documents i executi les ordres següents:
yarn global add docusaurus-init
ornpm install --global docusaurus-init
docusaurus-init
El resultat final serà la creació d'una estructura d'arxius i directoris com se'ns mostra a continuació:
Interessant bestiola a provar!