Je travaille pour une compagnie d'assurance. Nous avons notre propre département de développement composé de près de 150 personnes plus quelques fournisseurs (externalisation et applications sur mesure à peu près). Dans notre entreprise, mon équipe a fait ce que nous appelons des bibliothèques logiques non fonctionnelles. C'est-à-dire, les bibliothèques de logiciels pour gérer les choses qui sont horizontales à toutes les équipes de développement dans notre département, par exemple. Sécurité, Webservices, journalisation, messagerie et ainsi de suite. La plupart ou ces outils sont fabriqués à partir de rien ou en adaptant une norme de facto. Par exemple, notre enregistreur est un appender basé sur Log4J qui enregistre également les messages de journalisation dans une base de données. Nous définissons également les bibliothèques à utiliser dans l'application, par exemple le framework pour les services Web à utiliser. Nous utilisons à peu près JavaEE et Oracle AS dans toute notre organisation (avec des serveurs d'applications Websphere).Liste de vérification de la documentation de l'environnement logiciel
La plupart de ces projets ont leur architecture documentée (cas d'utilisation, diagrammes UML, etc.) et généralement la documentation générée est disponible. Maintenant, ce que nous avons vu, c'est que pour les utilisateurs, il est parfois difficile d'utiliser les bibliothèques que nous fournissons et ils posent constamment des questions ou ne les utilisent tout simplement pas.
Nous avons donc l'intention de générer une documentation plus conviviale pour eux, donc ma question est: Quelles sont les meilleures pratiques ou la liste de contrôle que la documentation logicielle devrait avoir?
Quelque chose vient à l'esprit:
- API Guide de référence
- démarrage rapide Tutoriel
- API Documentation générée.
- Doit être consultée
- Web Access
Que faut-il avoir? Aussi, d'après votre expérience, quelle est la meilleure façon de maintenir (maintenir à jour) et de publier ce type de documentation?