Sto scrivendo documentazione per un'interfaccia utente Ajax interattiva, ma invece di scrivere tutto a parole preferisco fornire diagrammi più veloci di interi paragrafi di testo. Ho fornito il diagramma flusso di navigazione della pagina, ma questo è un livello molto alto prima di approfondire le singole pagine e il loro funzionamento interno.
Esempio
Supponiamo di dover documentare un tipico pannello di ricerca:
- è compresso per impostazione predefinita e può essere espanso al clic
- ha campi di ricerca di base che forniscono criteri di ricerca di base sulla mia entità modello
- ha anche campi avanzati che mostrano quando si fa clic su un particolare collegamento che espande la ricerca con campi aggiuntivi
- ha due azioni Search e Reset che sono praticamente auto esplicative, ma hanno comportamenti particolari ad esse associati
So che dirai che questa è già una documentazione, ma di solito non è così semplice e banale. Il pannello di ricerca è solo un esempio.
Vedo che la maggior parte delle mie interfacce (o dei componenti dell'interfaccia) richiedono due tipi di documentazione:
- proprietà relative ai controlli contenuti (ad esempio, campo a discesa con questi e quei valori di cui quella particolare è selezionata per impostazione predefinita)
- azioni e comportamenti che descrivono cosa succede quando l'utente interagisce con i controlli relativi a tali proprietà