Notre quotidien de créateur de l'univers numérique, dans toute sa complexité, nous amène à expliquer et décrire ce que nous allons faire, faisons et avons fait.
Que l'on soit développeur, architecte, fonctionnel ou autres, un des moyens de communiquer est la documentation. Partir d'une page blanche peut paraître impressionnant devant la multitude des possibilités autour de ces pratiques. Des outils et des approches nous permettent de simplifier cette tâche tout en restant efficace et pertinent.
Du choix de ces outils aux stratégies d'organisation, nous vous proposons une série d'articles qui pourrait simplifier vos quotidiens de rédacteur.
Se lancer dans la documentation as code
Parmis ces outils, la documentation as code (ou avec le code) est un de ceux qui nous est cher.
Beaucoup d'entre nous, connaissons ce terme. En particulier à travers une de ses syntaxe, le markdown.
Ce format s'est plus ou moins imposé comme un standard, ou du moins, comme une habitude.
Il existe cependant des alternatives avec des écosystèmes bien plus fournis et aussi bien supportées que MD.
@arcanneero vous propose de faire un tour de ces alternatives, donc une en particulier. Au travers un ensemble d'articles vous aidant à en place, petit à petit, votre doc as code.
La doc as code, ça commence par écrire de la doc.
Sonnant comme une évidence, cette petite phrase est pourtant un adage important pour vous inviter à vous lancer dans la production de documentation.
Suivez les étapes pour aborder ces concepts avec l'article : "Doc as code, petit guide illustré pour mieux se lancer".
Ecrire de la doc, c'est bien. La mettre à disposition, c'est mieux.
Souvent un des points durs dans le parcours de mise en œuvre des documentations as Code, la publication est souvent prise comme une montagne infranchissable.
Deuxième article de la série, l'article "Doc as code, un parcours initiatique pour publier !" vous invite à mettre en place l'outillage nécessaire pour vous permettre de vous concentrer sur le contenu et laissez le contenant se mettre en place (presque) tout seul.
Écrire et publier sont deux composantes essentielles de la documentation, mais on arrive rapidement à une problématique de rangement, d'organisation, etc...
La question de la documentation utile devient alors indispensable à la suivie de vos projets !
La doc utile
L'outillage est prêt, le process de publication aussi. Maintenant, il faut s'attaquer au contenu.
Combien de fois sommes-nous tombés sur une documentation mal organisée ou incompréhensible ?
@yannschepens nous propose une série d'article sur le sujet, vous invitant à vous interroger sur ce qui peut rendre votre contenu utile.
Elle est où la doc ?
Cette question raisonnement tellement souvent dans nos oreilles que vous ne pouvez y être insensible.
Pour essayer de rendre nos documentations accessibles et utiles, un premier article vous propose de commencer par réfléchir à comment "écrire une doc technique utile".
Vous trouverez quelques conseils et une approche pour vous aider à y répondre
Donnez aux lecteurs ce qu'ils veulent
Facile à dire, et encore plus lorsque l'utilisateur lui même ne sais pas ce qu'il cherche !
Pour autant, une documentation ne se lit pas comme un livre.
Il ne faut pas avoir besoin de tout lire pour trouver l'information recherchée. Il existe pour cela des stratégies d'organisation qui sont abordées dans le second article Structurer votre doc pour la rendre utile.
Vous avez rédigé votre documentation, puis vous l'avez publiée, avant de la structurer pour la rendre utile et adaptée à vos lecteurs.
Reste à la rendre plus agréable visuellement.
Rendre la lecture agréable
Lire une doc c'est plus sympa quand elle est jolie
Au delà du fait que le joli est très personnel, vous pouvez être contraint à cause de charte graphique, ou autres règles internes à votre structure.
Il vous faut alors styliser vos publications, ce que les générateurs peuvent faire. Même si certains aspects peuvent être obscurs voir clairement étrange, c'est faisable ! Pour vous mettre le pied à l'étrier, "Doc as code, personnaliser vos rendus pour répondre à vos contraintes ou à votre esprit créatif !" vous donnera des pistes et quelques exemples de configuration pour vous simplifier la vie.
Conclusion
Rédiger de la doc demande de répondre aux : Comment ? Quand ? Qui ? Où ? Quoi ? La documentation as code présentée par @arcanneero et la façon de l'organiser peuvent vous permettre en partie de répondre à ces questions.
Inspirez-vous, testez les approches, critiquez-les, et profitez-en pour rédiger un petit article ou une documentation sur la documentation.
A vos claviers !
Les deux séries d'articles :
- Documentation as code par @arcanneero : https://dev.to/arcanneero/series/26267
- Écrire une doc technique utile par @yannschepens : https://dev.to/yannschepens/series/26510
Top comments (0)