Joel Spolsky passe par un series of blog post (4 messages) concernant la documentation technique par rapport à la documentation fonctionnelle. Sa série se concentre sur les spécifications fonctionnelles.
L'un des principaux points mentionnés est La différence entre une spécification fonctionnelle et technique:
Une spécification fonctionnelle décrit comment un produit fonctionnera entièrement du point de vue de l'utilisateur. Il ne se soucie pas comment la chose est mise en œuvre. Il parle de fonctionnalités. Il spécifie les écrans, les menus, les boîtes de dialogue, etc.
Une spécification technique décrit l'implémentation interne du programme. Il parle de structures de données, des modèles de bases de données relationnelles, le choix des langages de programmation et des outils, des algorithmes, etc.
Il continue de faire un point très important de l'OMI qui est que « une spécification est un document que vous voulez que les gens lire ", et mon 2c, et continuera à être lu.
Il donne un aperçu aussi de nombreux conseils sur le contenu des spécifications fonctionnelles. Toute la série est une bonne lecture. Si je ne me trompe pas, il fournit également un lien pour échantillonner les spécifications fonctionnelles.
Cependant, dans toutes les situations, je ne pense pas que vous devriez être dogmatique de suivre une méthode «prescrite» pour créer de tels documents (y compris le conseil de Joel). Soyez pratique et créer des documents qui sont faciles à lire etmaintenable parce que nous savons tous combien rapidement obsolètes ils peuvent devenir. On dirait que je parle de code - mais je suppose que les mêmes principes s'appliquent.
Les deux groupes de documents auront un public cible différent, donc connaître votre public cible.
Une image indique des milliers de mots, donc utiliser des diagrammes simples le cas échéant.
Je ne veux pas lire une série de 13 volumes sur ce que fait le système ou comment cela fonctionne. Alors soyez concis.
La structure du document est importante, mais je suggère de ne pas se concentrer sur cela initialement. Comprenez et identifiez toutes les petites pièces qui constituent la documentation et, en dernier lieu, compilez-la dans un document lisible. Ne laissez pas le mantra Table of Contents conduire votre création de documentation. Tableau blanc l'idée/les zones/le contenu en premier.
Chaque section devrait avoir une introduction et une conclusion décentes.