Pourquoi écrire des documents de conception de logiciels est important

Félicitations, vous êtes un développeur indépendant compétent. Depuis vos humbles débuts, peut-être en tant que testeur, vous avez évolué vers un développeur d'équipe, puis un développeur senior, et maintenant vous avez fait un autre saut, le plus grand de tous, pour travailler directement avec les clients.

Mais là où les autres transitions étaient linéaires, cette dernière était exponentielle. Alors que dans le passé, vous receviez vos ordres de marche d'un employeur qui travaillait avec des clients ou était lui-même dans le secteur des logiciels, maintenant toutes ces responsabilités qui étaient autrefois réparties entre les tests d'experts, la gestion de programme, etc., sont toutes à vous. Et maintenant, vous travaillez avec des clients qui ne sont pas dans le secteur des logiciels ; ils sont dans une autre entreprise qui a besoin d'un logiciel, et ils n'ont pas une vision claire et précise de ce qu'ils attendent de vous. C'est un défi bien plus grand qu'il n'y paraît.

*Remarque :* Ici, je décris des clients plus petits qui veulent une armée d'un seul homme de la part de leur développeur. Ce n'est pas la seule voie qu'un pigiste peut emprunter, et ce ne sont pas les seuls clients avec lesquels nous travaillons chez Toptal, mais c'est la voie que j'apprécie le plus. Bien sûr, si vous travaillez en équipe et non seul, certains des éléments ci-dessous ne s'appliqueront pas. Par exemple, si vous utilisez les méthodologies Agile ou Scrum, vous voudrez probablement structurer vos jalons légèrement différemment.

Vous avez tous entendu parler de l'importance suprême de la communication. Vous ne pouvez pas travailler en obtenant quelques phrases de description laconique sur Skype et en disant « On se voit dans trois mois quand j'aurai terminé ». Vous devez être en communication avec votre client et à chaque étape de votre travail vous assurer d'avoir des idées cohérentes sur l'objectif, car il est en effet rare qu'un client vous envoie des wireframes et un cahier des charges fonctionnel détaillé. Vous aurez une idée très générale de ce que le logiciel est censé faire, ressembler et suivre. Si vous écrivez une application basée sur la description sommaire avec laquelle vous commencez habituellement, il n'y a presque aucune chance que votre client soit satisfait du résultat. À chaque étape, vous devez itérer votre chemin vers un accord.

Ayant travaillé pendant des années dans des entreprises qui étaient elles-mêmes dans le domaine des logiciels, où tous les membres de l'équipe étaient de la même culture, parlaient la même langue maternelle, travaillaient dans le même couloir, se rencontraient quotidiennement, etc., il était remarquable que le l'entreprise n'obtenait toujours pas ce qu'elle voulait la moitié du temps. Ne vous méprenez pas : le défi ici est énorme.

Pourquoi les documents de conception de logiciels sont importants

Ainsi, lorsque vous entreprenez un nouveau projet, avant même d'ouvrir Xcode ou Visual Studio, vous devez avoir des objectifs de conception clairs et convenus . Et ces objectifs doivent être établis dans un document de spécification. Si le client n'en a pas écrit, vous devez l'écrire et le lui soumettre pour examen avant même d'ouvrir votre IDE. Et si vous rencontrez un client qui dit : « Nous n'avons pas le temps pour les documents de conception », franchement, vous devriez vous éloigner du projet parce que vous avez des problèmes devant vous. La spécification n'a pas besoin d'être particulièrement longue; il peut ne s'agir que de quelques pages, mais il doit au moins présenter l'interface utilisateur, inclure des structures filaires (s'il existe un composant d'interface utilisateur) et définir des jalons d'achèvement.

Sans ce document, vous vous retrouverez dans une boucle d'équivoque acrimonieuse, les clients contestant ce qu'ils vous ont dit ou ce que vous leur avez dit, envoyant avec colère des copier-coller des communications précédentes, interprétant et argumentant jusqu'au moment où le client demande que vous apportez des modifications pour rendre l'application conforme à "ce qu'ils ont réellement demandé" et s'attend à ce que vous apportiez ces modifications sans rémunération.

Avec ce document de conception de logiciel, vous aurez une réponse à toute question de ce genre : en cas de désaccord, vous pouvez vous référer à la spécification que le client a acceptée et signée, en soulignant que vous l'avez remplie à la lettre. Au lieu d'arguments en colère, vous apporterez des modifications et des clarifications au document. Au contraire, le client s'excusera d'avoir laissé passer l'imprécision en premier lieu.

Nous voulons tous des clients satisfaits. Nous voulons tous une relation de travail amicale. Et nous voulons tous la fierté du travail bien fait. Mais ceux-ci ne peuvent pas être atteints s'il y a le moindre flou sur ce qu'est réellement le travail. Si votre client dit qu'un document de conception représente trop de travail supplémentaire, c'est à vous de lui expliquer que le véritable travail supplémentaire apparaîtra lorsque des révisions devront être apportées en raison d'un malentendu. Si le client insiste toujours pour que vous avanciez sans un tel document, vous devez accepter le fait que vous avez une relation irréalisable et vous retirer.

Que doit réellement spécifier la spécification de conception logicielle ?

À tout le moins, il devrait s'agir d'une description de l'application souhaitée, des critères d'achèvement et des étapes. N'oubliez pas que vous partagez ce qui est décrit comme un document d'exigences et de fonction, et non comme une spécification d'implémentation. Et à moins qu'une mise en œuvre spécifique ne soit un objectif client déclaré, la façon dont vous la faites fonctionner dépend de vous.

Interface utilisateur

La plupart des projets sont des applications, pas des bibliothèques ou des frameworks. Mais s'il vous arrive d'en avoir un comme livrable, comptez-vous chanceux car l'interface utilisateur est de loin le composant le plus problématique de votre modèle de document de conception et conduit presque toujours à des malentendus. De nombreux clients vous enverront des illustrations parfaites créées dans un éditeur graphique par un graphiste qui n'est pas programmeur. Mais le problème est le suivant : ces illustrations ne disent rien sur les animations, les états des commandes (par exemple, ce bouton est-il désactivé ? Disparaît-il lorsqu'il est inutilisable ?), ni même sur les actions à effectuer lorsqu'un bouton est enfoncé.

Avant de commencer à écrire le code derrière ces illustrations, vous devriez être en mesure de répondre à toutes ces questions. Plus précisément, vous devez savoir :

1. Les contrôles sont-ils toujours visibles et/ou activés ? Dans quelles conditions leurs états changent-ils ?
2. Ressemble à un bitmap—est-ce un bouton ?
3. Quelles transitions se produisent entre ces états et ces vues ? Et comment les animer ?

Si c'est à vous de générer l'interface utilisateur pour l'accord du client, faites la même chose en sens inverse : utilisez un outil filaire et créez un ensemble complet de dispositions d'écran, y compris toutes les variantes que les vues affichent dans différents états d'application. Cela peut être un travail exhaustif et fastidieux, mais vous ne le regretterez pas, cela peut vous éviter de réécrire d'énormes quantités de code et de recréer des interfaces en raison d'un malentendu mineur avec des implications majeures. Si vous créez une double application (par exemple, pour iPhone et iPad), créez des wireframes distincts pour les deux.

Les dimensions de l'écran sont également importantes. Il existe (au moment de la rédaction) trois tailles d'écrans d'iPhone. Des wireframes séparés pour les écrans 3,5" et 4" sont probablement excessifs, mais vous devrez peut-être les créer ; dans la plupart des cas, vous pouvez simplement modifier les proportions.

Si votre client vous fournit des graphiques, assurez-vous qu'ils sont correctement dimensionnés avec les proportions appropriées ; le morphing de tout bitmap contenant du texte ou des objets (comme des cercles) introduira des distorsions. S'ils ne correspondent pas, dites au client de les recréer avec des tailles correspondantes. Ne présumez pas que vous pouvez étirer un écran de démarrage de 3,5 pouces en un écran de 4 pouces et simplement rouler avec.

Fonctionnalité

Questions clés à poser dans le document de conception de l'application :

• Que fait l'application et à quelle vitesse le fait-elle ?
• Quelles sont les conditions de défaillance possibles et comment sont-elles gérées ?
• Quelles opérations ponctuelles sont effectuées lors de la première exécution (c'est-à-dire après l'installation) ?
• Si l'utilisateur crée des entrées de n'importe quel type (par exemple, des signets), quelles sont les limitations ?

Généralisez ces idées et soyez aussi détaillé et approfondi que possible, car les erreurs ou les malentendus ici signifieront la réécriture du code.

Jalons

Votre modèle de spécification doit présenter des jalons clairs. Si votre client rédige la conception fonctionnelle et de l'interface utilisateur, vous devez ensuite vous mettre d'accord sur un ensemble de jalons. Parfois, il s'agit également de seuils de facturation, mais à tout le moins, ils fournissent une mesure claire de l'achèvement. Les jalons peuvent être en termes de fonctionnalité et/ou de composants ; il peut même s'agir d'applications distinctes si le concert implique une suite de livrables. Dans la mesure du possible, les jalons doivent être à peu près égaux en durée.

Exemple de spécification de conception de logiciel

Ici, je vais mettre en page l'exemple de structure d'un document de conception approprié. Bien sûr, ce modèle doit être ajusté selon les besoins. Pour un autre exemple, voir l'exemple de spécification de Joel Spolsky, basé sur cette rédaction. Il aborde le document légèrement différemment, mais partage un sentiment similaire.

Énoncé des objectifs

Inclure un court paragraphe décrivant le projet et son public cible.

mode d'emploi

A quoi sert l'application ? Quels états d'application (descriptions de haut niveau des scénarios utilisateur principaux) l'utilisateur rencontrera-t-il ?

Par exemple, votre description fonctionnelle pourrait ressembler à :

• Première exécution
• Création d'un nouveau _____ (jeu, recherche, etc.)
• Opérations
• Comportement d'arrière-plan et de premier plan

Interface utilisateur

Incluez des wireframes pour chaque page, avec des descriptions détaillées de :

• Chaque contrôle, y compris les états (activé/désactivé/en surbrillance) et les opérations.
• Orientations prises en charge et transitions entre elles.
• Fonctionnalité représentée.
• La gestion des erreurs.
• Dimensions et contraintes.

Voici les wireframes liés à ma dernière application iOS, NotifEye :

Si cela vous intéresse, j'ai réalisé ces maquettes à l'aide de l'outil de wireframing de Balsamiq.

Par exemple, la description de votre interface utilisateur pourrait ressembler à :

• Barre de navigation
  • Commande de navigation gauche : retour à la page d'accueil
  • Barre de titre : écran actuel ou nom de l'opération
  • Nouveau bouton : créer une nouvelle chose
• Vue de tableau
  • Rubrique 0 : Titre de la rubrique
  • Section 0 rangées :
    • Contrôle de ligne 0 (par exemple, image)
    • Ligne de texte 0
    • Ligne de texte 2

Jalons

Comme décrit ci-dessus, les délais d'achèvement et les livrables attendus.

Par exemple, la section des jalons dans votre modèle de document de conception peut ressembler à :

1. Application de façade montrant l'écran et avec des transitions temporaires et des exemples d'images/texte
2. Protocole de communication : l'application se connecte au réseau/serveur
3. Jalon fonctionnel 1 : …
4. Application Alpha (avec toutes les fonctionnalités)
5. La stabilité
6. Libérer

S'assurer que la documentation du logiciel reste pertinente

Je ne veux pas dire que la phase de conception est terminée une fois que vous et votre client vous êtes mis d'accord sur un document de spécification. Il y aura toujours des détails qu'aucun de vous n'avait pris en compte, et vous et le client rencontrerez, en examinant les résultats intermédiaires, de nouvelles idées, des modifications de conception, des défauts de conception inattendus et des suggestions irréalisables.

La conception évoluera et les changements devraient être capturés dans votre document. Au cours de mes 25 années d'expérience, je n'ai jamais travaillé sur un projet où cela ne s'est pas produit, et cela inclut mes propres applications (c'est-à-dire, où j'étais mon propre client). Même alors, j'ai créé un document de conception avec des spécifications détaillées et je l'ai ajusté si nécessaire.

Surtout, restez en contact. Au moins plusieurs fois par semaine, contactez votre client, faites-lui part de vos progrès, demandez des éclaircissements et assurez-vous que vous partagez des visions identiques. Comme test décisif pour votre communication, essayez de vous assurer que vous et votre client donnez les mêmes réponses à ces trois questions :

1. Sur quoi le développeur travaillait-il ?
2. Sur quoi le développeur travaille-t-il actuellement ?
3. Sur quoi le développeur travaillera-t-il ensuite ?