Manuali - Quanto aggiornato?


10

Se hai un prodotto che è sul mercato da molto tempo, ma è ancora in fase di sviluppo attivo ogni giorno - con quale frequenza è necessario aggiornare i manuali? Se gli utenti vengono costantemente aggiornati alla versione bleeding edge a causa del fatto che l'organizzazione ritiene che le ultime correzioni dei bug siano sempre nella versione fornita. Cioè, potresti risolvere un bug un giorno e il giorno successivo sta colpendo la produzione.


1
Stiamo parlando di manuali stampati o online? Ci sono almeno un paio di forme diverse che questo può assumere.
JB King,

Manuali online (PDF)
Brian,

Risposte:


4

Vorrei aggiornare il manuale:

  1. Per ogni versione principale e
  2. Quando nuove importanti funzionalità diventano abbastanza stabili e mature da sapere che non cambieranno ogni cinque minuti.

3

aggiornare il manuale (PDF) ogni volta che una modifica del codice altererebbe le istruzioni nel manuale - basta aggiornare la parte manuale del processo di rilascio

se gli utenti fanno affidamento sul manuale per dire loro come utilizzare il prodotto e il prodotto cambia, è solo logico che anche le sezioni pertinenti del manuale debbano cambiare


1
quindi se nessuno scrittore tecnico fa parte dello staff, aggiornalo tu stesso?
Brian,

@ 0A0D - se non hai uno scrittore, non hai molta scelta, a meno che non ci sia personale addetto ai test o al supporto che può farlo.
JeffO,

1
Ho il documento "file sorgente" come parte dei miei progetti. Vengono sempre aggiornati contemporaneamente al codice. Sono versioni con versioni e gestite utilizzando gli stessi strumenti managmnet di origine del resto dei file di progetto (vai su Mercurial!). Ho un set abbastanza standard di manuali da abbinare a un progetto e questi sono tutti gestiti allo stesso modo (guida per l'utente, guida di configurazione / installazione, note di rilascio e nostri documenti di riferimento / specifiche tecniche).

2

Nel 2010 ci riferiamo ancora alla documentazione stampata? Perché? ;)

In tutta serietà, la documentazione (guida all'applicazione "F1", PDF o documentazione online) dovrebbe far parte di ogni singola versione. Zero scuse. È così semplice "pubblicare". È un dato di fatto, IMO, non ci sono scuse per non aggiornare la documentazione su base regolare (online e PDF), anche tra le versioni, non appena i problemi sono noti e corretti. Non ha bisogno dello stesso livello di QA - nemmeno vicino.


2

Presumo che tu stia parlando della documentazione per l'utente finale. Scrivere documentazione è un dolore in @ $$ e mentre ho sviluppato una tecnica per convincermi del contrario, ho ancora problemi con questo. Ecco come provo a gestirlo:

Integra l'aggiornamento della documentazione nel tuo DoD ( Definizione di done )

Ciò assicurerà che la documentazione sia aggiornata alla fine di ogni completamento della storia dell'utente.

Ecco la definizione di fatto che abbiamo scritto. Ho provato a mantenere le formattazioni originali, quindi hai avuto l'idea. È una pagina A4 messa sulla lavagna.

---------- 8 <------------ Taglia qui ------------ 8 <----------

Non negoziabile

Definizione di “Fatto”

  • Codice con copertura del test unitario dell'80%, impegnato in repository

  • Schermate se applicabili (1024x728, 395x281, 170x121 e 729x329)

  • Descrizioni delle funzioni se applicabili (50 caratteri, 100 caratteri)

  • Documentazione completa per l'utente finale

  • Novità del file aggiornato correttamente

---------- 8 <------------ Taglia qui ------------ 8 <----------

Ovviamente puoi aggiungere un processo di revisione nella documentazione. Lo abbiamo visto che nessuno di noi è di madrelingua inglese.

Uno dei vantaggi della definizione di Fatto come questo è che il tuo prodotto è potenzialmente spedibile al termine di ogni completamento della storia dell'utente.

Usa questa tecnica in combinazione con questa .


1

Nella mia organizzazione, in genere abbiamo 3 tipi di versioni:

  1. Versione tecnica: sostanzialmente una correzione rapida per un cliente specifico o alcune funzionalità che solo un cliente particolare ha richiesto su base immediata.
  2. Rilascio minore: correzioni di errori, supporto incrementale
  3. Rilascio principale: supporto di nuove funzionalità ecc.

Per definizione, la versione principale deve disporre della documentazione pertinente sia online che offline. Il nostro sistema di tracciamento garantisce che la documentazione sia parte integrante dell'elenco di controllo.

Le versioni minori necessitano di documentazione solo su tutto ciò che è stato aggiunto a livello di percezione dell'utente. Quindi, se hai incluso un altro euristico che potrebbe ridurre la complessità temporale in alcuni scenari specifici, potrebbe essere o meno una chiamata significativa metterlo nel pdf.

Le versioni di ingegneria potrebbero fare a meno della documentazione. Alcune note sull'uso informale dovrebbero essere abbastanza buone per iniziare.


0

La documentazione deve essere sincronizzata con qualsiasi software si stia spedendo a un cliente. Qualsiasi altro errore di corrispondenza ti darà problemi. E se non hai uno scrittore nello staff, prova gli appaltatori. Una volta trovato quello che ti piace, tienilo in stato di fermo.

Utilizzando il nostro sito, riconosci di aver letto e compreso le nostre Informativa sui cookie e Informativa sulla privacy.
Licensed under cc by-sa 3.0 with attribution required.