Archivi categoria: documentazione

Come scrivere i requisiti – la Guida di INCOSE

La scrittura dei requisiti è importante per qualunque progetto. È importante perché ogni ambiguità nei requisiti provoca danni per i progetti: aumento dei difetti nei prodotti, aumento dei costi, ritardi nei tempi di realizzazione.

La Guida per la scrittura dei requisiti (“Guide for Writing Requirements”), pubblicata da Incose (International Council on Systems Engineering) nel 2019, fornisce indicazioni utili e concrete per la redazione delle specifiche.

Non è certamente l’unica guida disponibile: sulla scrittura dei requisiti sono stati pubblicati molti libri e centinaia di articoli.

La Guida per la scrittura dei requisiti di Incose ha comunque un paio di punti di forza che la distinguono:

  • È frutto del lavoro ultradecennale del Requirements Working Group di Incose, formato da aziende ed esperti che operano in settori critici dell’ingegneria dei sistemi e del software
  • È conforme allo standard ISO 29148: 2018 (“Systems and software engineering — Life cycle processes — Requirements engineering”)

Una sintesi degli elementi chiave della Guida per la scrittura dei requisiti (che ha avuto un aggiornamento minore nel 2022) è disponibile qui: https://analisi-disegno.com/guida-per-la-scrittura-dei-requisiti/

La versione completa della Guida è disponibile sul sito di INCOSE: https://www.incose.org

Documentare il software con l’intelligenza artificiale?

Con cautela, per ora. Scrivere la documentazione tecnica è faticoso, ma è una competenza utile a tutti coloro che sono coinvolti nello sviluppo software. Almeno per verificare la qualità della documentazione prodotta con l’intelligenza artificiale.

“A volte mi chiedo se dovremmo iniziare tutta la nostra scrittura, compreso il software, a mano invece di usare il computer. Il processo di scrittura a mano incoraggia la riflessione e scoraggia il copia e incolla”.

Phil Laplante: “Use a Pencil: On Writing Software Documentation Well and the Role of Autodocumentation”, IEEE Computer, May 2024

https://www.computer.org/csdl/magazine/co/2024/05/10517734/1WCj99UUwh2

Plain Language

Scrivere in modo semplice (Plain Language) per farsi capire meglio da chi ci leggerà.

E’ importante sempre, e lo è in particolare per le specifiche dei requisiti e di analisi dei sistemi informatici, condivise e lette da persone con ruoli diversi:

  • committenti, utenti e altre parti interessate (stakeholder)
  • progettisti e sviluppatori software
  • tester (verificatori del corretto funzionamento del sistema)
  • redattori di manuali operativi

In questa pagina ho riportato una serie di indicazioni e riferimenti: Scrivere in modo semplice.

Un articolo recente del Nielsen Norman Group sottolinea l’importanza del Plain Language anche quando si scrive per un pubblico di esperti: Plain Language Is for Everyone, Even Experts.

Arc42, per documentare le architetture software

Arc42 è un framework semplice e concreto per documentare le architetture software. L’impostazione è essenziale, ma completa.

Basato su una serie di template, è stato realizzato da Gernot Starke e Peter Hruschka, ed è usabile  gratuitamente e senza vincoli. Prevede come opzione, anche se non obbligatoria, l’uso di UML.

Le caratteristiche di Arc42 vengono spiegate in questa intervista su Software Engineering Radio.