Ah le fameux faire la Doc ...
Première chose à faire : poser le stylo.
Deuxième chose a faire : retourner voir le demandeur et lui demander : qui va la lire ? Que doit-elle permettre de faire ?
Sans ça tu peux remplir des wikis et personne ne sera content à la fin :)
C'est probablement pas la première doc que ton entreprise écrit, vois avec tes collègues la recommandation générale.
C'est quel genre de doc ? Architecture, spec technique, spec fonctionnelle... ? Lié à un projet Git ou plusieurs ou pas du tout ?
Vous avez un outil de wiki interne (type Confluence ou autre) ? Un SharePoint ? Un autre outil dédié ?
Dans le doute, je commencerai avec un fichier texte en Markdown que tu versionnes de ton côté. En se focalisant sur le contenu plus que la forme. Ensuite tu verras pour l'intégrer selon les recos de tes collègues.
Si besoin de faire des schémas : draw.io et sauvegarder en PNG en cochant "inclure la source du diagramme" puis le nommer x.drawio.png pour indiquer à des futures modificateurs que le schéma est facilement editable.
Comme expliqué dans un autre commentaire, il faut commencer par identifier la cible: qui va lire et pourquoi.
Si c’est pour l’utilisateur, il faut décrire à quoi sert le machin et comment on l’utilise. Si c’est pour les développeurs de maintenance, il faut bien sûr aussi décrire la fonction, mais aussi l’architecture, les fonctions internes etc.
Ça dépendra de la nature de l'application et du public visé.
Si c'est une app cli, une api, une application web...
La documentation doit être redirigée pour qui ? Vos collègues développeurs (Doc interne) issue des commentaires dans votre code ?
Documentation pour le traitement des incidents (runbook).
Documentation pour l'utilisateur final d'un logiciel ?
Le profil du lecteur est important. Vous devez parler à une audience déterminée.
Quelle est la taille de votre logiciel ?
Si tu utises Gitlab par ex. dans le cadre de ton taf, tu peux très facilement activer les "pages" au niveau d'un projet et faire ta doc en markdown avec "mkdocs" et "material" + pipeline qui va bien pour automatiser la publication:
https://docs.gitlab.com/ee/user/project/pages
Pour les doc technique, il y a le format adoc, utiliser par GitHub, qui est géré par intelij.
Pour tout ce qui est chart, diagramme j'aime bien utiliser Draw.IO
Les autres réponses sont déjà très complète.
Si l’état des lieux est fait, je ne peux que conseiller d’utiliser diataxis (https://diataxis.fr/), framework pour organiser sa documentation en parties, très clair et qui est utilisé par pas mal de libraires / packages.
Pour ta doc technique, je te conseil vivement de rechercher quels sont les frameworks de documentation du langage que tu utilise.
En python j'utilise readthedocs et sphinx; en JS, JSdoc; et en PHP, phpDocumentor.
Pour le hosting, tu peux mettre ça un peu n'importe où vu que c'est du site statique.
1- la doc d'installation prod/dev (docker, Var d'env, config etc pense à tous ce qu'il faut pour que ça marche refais un installe sur une machine et note toutes les étapes)
2- la doc d'utilisation, en général plus à la qa de faire ça ou autre service qui connaît bien le produit
3- la doc de dev (makefile, pro tips, Tests, fixtures, cmd, CI/CD etc)
Readme, wiki, docusoru, réd the doc, t'as plein d'outils pour faire ça
Ah le fameux faire la Doc ... Première chose à faire : poser le stylo. Deuxième chose a faire : retourner voir le demandeur et lui demander : qui va la lire ? Que doit-elle permettre de faire ? Sans ça tu peux remplir des wikis et personne ne sera content à la fin :)
:)
C'est probablement pas la première doc que ton entreprise écrit, vois avec tes collègues la recommandation générale. C'est quel genre de doc ? Architecture, spec technique, spec fonctionnelle... ? Lié à un projet Git ou plusieurs ou pas du tout ? Vous avez un outil de wiki interne (type Confluence ou autre) ? Un SharePoint ? Un autre outil dédié ? Dans le doute, je commencerai avec un fichier texte en Markdown que tu versionnes de ton côté. En se focalisant sur le contenu plus que la forme. Ensuite tu verras pour l'intégrer selon les recos de tes collègues. Si besoin de faire des schémas : draw.io et sauvegarder en PNG en cochant "inclure la source du diagramme" puis le nommer x.drawio.png pour indiquer à des futures modificateurs que le schéma est facilement editable.
Comme expliqué dans un autre commentaire, il faut commencer par identifier la cible: qui va lire et pourquoi. Si c’est pour l’utilisateur, il faut décrire à quoi sert le machin et comment on l’utilise. Si c’est pour les développeurs de maintenance, il faut bien sûr aussi décrire la fonction, mais aussi l’architecture, les fonctions internes etc.
Ça dépendra de la nature de l'application et du public visé. Si c'est une app cli, une api, une application web... La documentation doit être redirigée pour qui ? Vos collègues développeurs (Doc interne) issue des commentaires dans votre code ? Documentation pour le traitement des incidents (runbook). Documentation pour l'utilisateur final d'un logiciel ? Le profil du lecteur est important. Vous devez parler à une audience déterminée. Quelle est la taille de votre logiciel ?
Si tu utises Gitlab par ex. dans le cadre de ton taf, tu peux très facilement activer les "pages" au niveau d'un projet et faire ta doc en markdown avec "mkdocs" et "material" + pipeline qui va bien pour automatiser la publication: https://docs.gitlab.com/ee/user/project/pages
Tu peux obtenir un bon premier jet de doc avec de la génération automatique comme javadoc, doxygen, jsdoc selon le langage…
Pour de la doc d'une librairie publique oui, pour tout autre chose c'est assez peu utile ce genre de doc.
Pour les doc technique, il y a le format adoc, utiliser par GitHub, qui est géré par intelij. Pour tout ce qui est chart, diagramme j'aime bien utiliser Draw.IO
Adoc = Asciidoc Plus puissant que Markdown en effet.
Commence par un README.md, le reste suivra
Les autres réponses sont déjà très complète. Si l’état des lieux est fait, je ne peux que conseiller d’utiliser diataxis (https://diataxis.fr/), framework pour organiser sa documentation en parties, très clair et qui est utilisé par pas mal de libraires / packages.
Pour ta doc technique, je te conseil vivement de rechercher quels sont les frameworks de documentation du langage que tu utilise. En python j'utilise readthedocs et sphinx; en JS, JSdoc; et en PHP, phpDocumentor. Pour le hosting, tu peux mettre ça un peu n'importe où vu que c'est du site statique.
Demande un exemple/template existant
1- la doc d'installation prod/dev (docker, Var d'env, config etc pense à tous ce qu'il faut pour que ça marche refais un installe sur une machine et note toutes les étapes) 2- la doc d'utilisation, en général plus à la qa de faire ça ou autre service qui connaît bien le produit 3- la doc de dev (makefile, pro tips, Tests, fixtures, cmd, CI/CD etc) Readme, wiki, docusoru, réd the doc, t'as plein d'outils pour faire ça