Design : Un guide pratique pour la rédaction d’un document de conception technique de logiciel

L’approche de l’analyse des options itératives

Avertissement: Les méthodologies discutées dans cet article sont le résultat de mon expérience collective de toutes les dernières années dans les logiciels, le matériel et l’ingénierie en général. Ils ne représentent aucun point de vue d’aucune entreprise.

La rédaction du document de conception est pas seulement un aperçu de la façon dont vous concevez un logiciel pour communiquer avec d’autres personnes (comme des recettes) mais surtout, un outil permettant au concepteur de logiciels de se faire une idée concrète de la manière de résoudre un problème de manière systématique et critique.

Au fil des ans, j’ai itéré ma méthodologie pour l’écriture de conception de logiciels – je l’appelle, Analyse des options itératives (IOA). Dans l’article, je parlerai en profondeur de ce que c’est et de son fonctionnement. Je vais utiliser un exemple de construction d’une application de transcription comme exemple pour illustrer l’idée, tout au long de l’article

Problème

Contexte

Buts

Non-buts

Options de conception
Option 1
– Avantages
– Les inconvénients

Option 2
– Avantages
– Les inconvénients
…

Conclusion

Problème

Fournissez une description concise d’un problème à résoudre ou d’un processus à améliorer.

Problème

Nous aimerions concevoir une application Speech-to-Text pour les appareils Android. Un utilisateur peut appuyer sur un bouton de l’application et la transcription s’affichera à l’écran lorsque l’utilisateur parlera.

Contexte

Cette section décrit le contexte aux réviseurs et explique pourquoi nous devons résoudre ce problème.

Contexte

Selon des recherches récentes et des entretiens avec des conseils en brevets, nous avons remarqué qu’il existe un besoin croissant d’auto-dictée lors des entretiens avec leurs clients. Les conseils en brevets doivent également revoir les enregistrements vocaux originaux si la transcription n’est pas exacte.

Quel contexte dois-je fournir? Et si je peux écrire un livre d’histoire à ce sujet? Vous pourriez demander. Expliquez simplement de la même manière que vous expliqueriez les entretiens avec les candidats dans un court délai. Les candidats aux entrevues connaissent souvent un contexte presque nul de la façon dont votre entreprise construit les systèmes ou aucun jargon de votre entreprise. Le fond doit être concis et précis.

Portée / Objectifs

Cette section est souvent appelée In Scope, Goals, Tenets ou Requirements. Il décrit tout ce que vous voulez réaliser par cette conception. Je vois les objectifs comme des dirigeants de différentes dimensions, pour mesurer la qualité des options.

Buts

1. Le taux de précision de transcription peut avoir 90% et plus.
2. Les données binaires de la parole peuvent être capturées et stockées pour un futur audit.

Je vois les objectifs comme des dirigeants de différentes dimensions, pour mesurer la qualité des options.

Hors de portée / non-objectifs

Il est aussi souvent appelé non-objectifs. Comme le terme Hors champ, il trace des limites, à l’extérieur, qui ne seront pas prises en compte dans l’analyse des options. Chaque non-objectif doit être accompagné de raisons expliquant pourquoi il s’agit d’un non-objectif.

Un bon indice sur le moment où un non-objectif est nécessaire est qu’un réviseur vient vous demander pourquoi quelque chose n’est pas pris en compte dans votre conception, et vous avez une raison spécifique de ne pas l’inclure. Si vous pouvez mentionner de manière préventive des non-objectifs, cela éviterait des questions ou des lacunes lors de la révision finale de la conception.

Non-buts

1. Créez le processus d’audit des données vocales. Raison: nous déciderons de la façon de le construire plus tard. Actuellement, nous devons préserver les informations utilisateur et les données vocales.

Analyse des options de conception

Des millions (illimité, à mon avis) de moyens peuvent résoudre le même problème.

Par exemple, si vous souhaitez vous rendre à Los Angeles depuis San Francisco, vous pouvez conduire sur la Highway 1 ou l’Interstate 5, prendre un vol Delta ou marcher jusqu’à New York et revenir jusqu’à Los Angeles. Si vous optimisez à temps, le vol est votre meilleure option, et la marche semble scandaleuse et stupide. Si vous voulez assister à la beauté ultime de l’Amérique et avoir un temps illimité pour tuer, traverser le comté ne semble pas déraisonnable.

Choisissez les 3 ou 4 options les plus raisonnables à considérer. Compte tenu des limites des outils logiciels et de l’environnement, les options raisonnables sont souvent numérotées, mais rarement une seule.

Option 1: l’application appelle directement un service de reconnaissance vocale automatique basé sur le cloud (ASR)

Option 2: créer l’ASR intégré pré-formé dans l’application

Option 3: un service HTTP / 1.1 effectue des appels proxy vers un service de reconnaissance vocale automatique (ASR) basé sur le cloud

Option 4: un service RPC bidirectionnel pour proxy d’appels vers le service Google Speech-to-Text

Pour chaque option, décrivez en détail à quoi ressemble le système proposé. Soyez généreux avec les diagrammes! Comme le dit le vieil adage, « une image vaut mille mots ». Un diagramme est le meilleur outil pour illustrer un système.

Option 4: un service RPC bidirectionnel pour proxy d’appels vers le service Google Speech-to-Text

Comme le dit le vieil adage, « une image vaut mille mots ».

Pour chaque option, fournissez une liste exhaustive des avantages et des inconvénients. Chaque option devrait avoir le même poids de considération, peu importe à quel point elle sonne déjà pire que d’autres au début. Il est trop tôt pour tirer une telle conclusion sans analyse approfondie. Si vous avez du mal à trouver les avantages et les inconvénients, au début, ça va! Les objectifs peuvent vous donner quelques idées. Utilisez les objectifs pour mesurer cette option et voyez si elle est bonne ou mauvaise dans cette dimension.

Option 1: l’application appelle directement un service de reconnaissance vocale automatique basé sur le cloud (ASR)

Nous pourrions utiliser directement un service cloud tiers (tel qu’Amazon Autotranscribe, Google Speech-to-Text). L’application Android peut directement envoyer des demandes au service ASR et afficher immédiatement la réponse à l’écran.

Avantages
1. À l’heure actuelle, un service ASR mature tel qu’Amazon Transcribe est capable de fournir une précision de transcription de 95% et plus. (Cela répond à l’objectif n ° 1)
2. Pas besoin de configurer un serveur.

Les inconvénients
1. Les données binaires de la parole ne peuvent pas être capturées. (C’est contre l’objectif n ° 2)
2. Le service ASR tiers n’est pas gratuit.

S’il est facile d’articuler les avantages et les inconvénients sans l’aide des objectifs, vérifiez toujours les objectifs et voyez si vous avez manqué des objectifs qui vous intéressent.

Dans l’exemple ci-dessous, j’ai remarqué que nous nous soucions de la taille de l’APK Android et de la façon dont le processus de transcription est similaire, lors de l’analyse des avantages et des inconvénients. J’ai donc ajouté le pour et le contre liés à ces points, et j’ajoute également deux autres objectifs, puis je passe en revue d’autres options en gardant à l’esprit les nouveaux objectifs.

Buts

1. Le taux de précision de transcription peut avoir 90% et plus.
2. Les données binaires de la parole peuvent être capturées et stockées pour un futur audit.
3. Gardez la taille de l’APK Android sous 100 Mo.
4. Le processus de transcription doit être continu, ce qui signifie que l’utilisateur peut voir les transcriptions pendant qu’il parle.

…

Option 3: un service HTTP / 1.1 effectue des appels proxy vers un service de reconnaissance vocale automatique (ASR) basé sur le cloud

Nous pourrions mettre en place un service proxy entre l’application Android et un service cloud tiers (comme Amazon Autotranscribe, Google Speech-to-Text). Lorsque l’utilisateur appuie sur le bouton, les données binaires vocales sont enregistrées sur l’application et les envoient au service proxy. Lorsque le service proxy dirige les données vers le service ASR, il peut également récupérer les données et les stocker ailleurs (par exemple, Google Storage).

Avantages
1. Le service Google Speech-to-Text peut fournir une précision de transcription de 95%. (Cela répond à l’objectif n ° 1)
2. Les données binaires vocales peuvent être capturées et stockées. (Cela répond à l’objectif n ° 2)
3. L’application Android serait un client léger sans se transcrire. La taille de l’application ne peut pas augmenter de manière significative. (Cela répond à l’objectif n ° 3)

Les inconvénients
1. Un service supplémentaire doit être mis en place. Cependant, il est très facile de configurer un service avec HTTP / 1.1.
2. Le processus de transcription ne serait pas continu en raison de la nature unidirectionnelle du service HTTP / 1.1. (C’est contre l’objectif n ° 4)

Vous pouvez maintenant voir que cette approche est itérative – nous continuons d’améliorer chaque partie de l’analyse à mesure que de nouvelles idées surgissent.

Il est parfaitement normal que vous ayez un con ou un pro qui ne fait pas partie des objectifs. Ils peuvent être des points bonus ou des points moins.

N’oubliez pas qu’il n’y a pas de mauvaise option, mais une meilleure option dans le contexte des objectifs.

Conclusion

Sur la base de toute l’analyse approfondie, vous commencerez à voir la meilleure option commencer à émerger en ayant plus de pros ou tous les pros qui répondent aux objectifs. La solution choisie peut aussi avoir des inconvénients, qui ne sont souvent pas des disjoncteurs de décision. Dans cette section, nous pouvons également ajouter ce que nous ferons pour atténuer les inconvénients de l’option choisie.

Conclusion

Sur la base de l’analyse ci-dessus, l’approche proposée est l’option 4, qui répond à tous les objectifs.

Voir l’exemple complet ici.

Relecture

Regardez votre document de conception comme le document de quelqu’un d’autre et critiquez chaque déclaration.

• Voyez si des hypothèses sont faites sans preuves. Si oui, faites des recherches et ajoutez plus de preuves – Conception / code antérieurs, données historiques, etc.
• Voyez si les mots sont subjectifs. Si oui, supprimez les mots subjectifs. Voici quelques mots qui pourraient conduire à la subjectivité: «Je pense / Nous pensons», «Je / Nous ressentons», «Bon / Super / Nice», «Mauvais / Terrible», etc.
• Voyez si vous poseriez d’autres questions. Si oui, ajoutez des précisions pour couvrir les questions.

Choisir des réviseurs

Ceux qui comptent, les parties prenantes, alias les personnes qui seraient affectées par la conception. Ceux qui comptent sont les suivants mais ne sont pas soumis à –

• Chef de produit (qui se soucie de savoir si la conception répond aux exigences du produit)
• Coéquipiers (qui doivent être conformes à la conception. Parce qu’ils finiront par mettre en œuvre et maintenir le système)
• Ingénieurs de test (qui ont besoin de savoir comment ils testeraient l’implémentation finale)
• Équipes dépendantes (dont les systèmes sont les dépendances, les clients et les services en aval de votre système)

Dans une petite startup où les gens portent de nombreux chapeaux, il vaut toujours la peine de rassembler les gens pour examiner le document et fournir des commentaires.

Les plus expérimentés, a.k.a., les ingénieurs les plus expérimentés que vous êtes. Dans un environnement qui encourage l’apprentissage, chaque tâche doit être traitée comme une opportunité de grandir. Invitez des personnes expérimentées à venir vous défier. Parfois, ils peuvent simplement poser une question suffisamment importante pour faire une grande différence dans la conception. Tout au long du processus, vous venez d’apprendre quelque chose de nouveau.

À l’étude

Traitez le processus d’examen comme un processus de relecture. Traitez vos critiques comme des partenaires. Cependant, lorsque vous présentez le document pour examen, ce devrait être votre meilleure version.

Je traite toujours les commentaires des gens très au sérieux. S’ils ont des questions, c’est un signal que mon doc n’est pas assez clair et je dois répondre à leurs questions dans le doc.

Il est très important de limiter le processus d’examen. Définissez les attentes avec vos évaluateurs dans quel délai vous souhaitez que l’examen soit terminé.

Prendre une décision

Avant que le document ne soit présenté pour examen, vous devriez déjà avoir une conclusion préliminaire sur ce qu’il faut faire. Prenez en compte les commentaires des évaluateurs et voyez comment cela fausserait la conclusion, prenez une décision ensemble et gardez tous les évaluateurs sur la même page.

Voici quelques résultats courants –

• Allez avec l’option que vous avez conclue précédemment
• Passer à une autre option répertoriée
• De nouvelles options ont émergé et sont envisagées et prises
• Avoir une option comme solution à long terme et une autre option comme solution à court terme (elle est très courante dans un projet sensible au facteur temps)

L’analyse des options itératives peut également être appliquée à d’autres processus décisionnels réels.

Chez Roxy, lorsque nous contrôlions les fabricants de Roxy, nous avons également utilisé cette approche. Avec trois des fondateurs n’ayant aucune expérience préalable dans la fabrication, il serait difficile de commencer. Il y avait des milliers de fabricants à Shenzhen. Comment devrions-nous choisir celui pour Roxy?

Ensuite, nous avons commencé par énumérer ce qui nous importait (objectifs).

• Capacités des fabricants – s’ils peuvent produire en masse un haut-parleur intelligent avec OS.
• Fiabilité – s’ils ont les antécédents pour livrer à temps
• Stabilité – s’ils continueront d’être là mais ne feront pas faillite prochainement

Ensuite, nous avons commencé à rechercher des options en visitant les Expos, en discutant avec des investisseurs et des amis qui connaissaient la fabrication en Chine.

Au tout début, nous avions une longue liste d’options. En vérifiant par rapport aux objectifs, certaines options faibles ont été filtrées à un stade précoce. Les quelques autres seraient ceux que nous examinerions et plongerions profondément dans l’analyse. Pour connaître les avantages et les inconvénients, nous devions trouver des moyens de capturer plus d’informations. Certains n’étaient pas évidents à première vue, comme la stabilité financière. Nous aimerions demander à un ami qui connaissait bien l’industrie et obtenir ses commentaires. Nous avons visité leurs usines, discuté avec les propriétaires, observé le fonctionnement de leurs employés et la manière dont leurs managers les traitaient.

Les décisions sont difficiles à prendre pour la fabrication. C’est comme un investissement que vous engagez et croyez en leur capacité après avoir déposé l’argent (généralement en chiffres à 6 chiffres).