Come mantenere la guida dell'utente in linea con le filiali per un non sviluppatore?

6

La nostra guida per l'utente corrente è creata utilizzando asciidoc . La documentazione è gestita da una persona non tecnica, ma conserviamo i file di testo di origine e HTML generato nel controllo del codice sorgente. I problemi sorgono quando gli aggiornamenti dei doc vengono pubblicati per la versione x.z nel ramo x.y . In genere, uno degli sviluppatori aggiorna il proprio ambiente, ma può essere molto smemorato. So che ci deve essere un modo migliore per farlo.

Come gestisci le guide degli utenti in versione modificata senza in realtà dipendere da utenti non tecnici per l'apprendimento di VCS?

    
posta sarumont 14.03.2012 - 19:15
fonte

2 risposte

7

Quando la tua documentazione è sotto controllo di versione, è tipicamente non una richiesta irragionevole per la persona che fa la documentazione e / o gestisce la documentazione per assicurarsi che sia correttamente verificata - che siano uno sviluppatore tecnico o altro

Nella mia esperienza, una nota appiccicosa sul desktop (virtuale o meno) con i pochi comandi git / svn / etc, o il percorso di interazione con il proprio client GUI di scelta, sul desktop di una persona altrimenti non tecnica ha ha funzionato bene quando è stata chiarita la responsabilità e le aspettative che il controllo della documentazione è parte del lavoro.

Potresti non essere in grado di farlo nella tua situazione specifica, ma se tiriamo fuori "mio marito è il CTO e fa alcune cose per me" (nota: era nella domanda iniziale) e affrontato il problema in generale quindi alcune opzioni includono:

  • La persona impara come utilizzare il controllo della versione e fa parte del loro flusso di lavoro, come indicato sopra (e ancora, non irragionevole, sebbene il project manager o il responsabile tecnico o chiunque tenga d'occhio le cose potrebbero dover tenere d'occhio le cose le prime volte).
  • La persona non impara come usare il controllo di versione e il passaggio del flusso di lavoro per il controllo della documentazione ricade su qualcuno nel team di sviluppo o forse sul gestore di rilascio (a seconda di quando avviene il checkin).
  • Qualcos'altro probabilmente più complicato e inefficiente di una nota appiccicosa sul desktop su come effettuare il check-in di un documento ...
risposta data 14.03.2012 - 19:38
fonte
0

Bene, in quale ramo dovrebbe effettivamente fare gli aggiornamenti dei doc? In x.z, in x.y, o in entrambi? Se c'è un solo ramo, limita il suo accesso a quel ramo sul tuo server VCS. Se deve lavorare su entrambe le diramazioni in parallelo, è meglio insegnarle un po 'di più sul controllo della versione e assicurarsi che sia facile vedere su quale ramo sta lavorando.

    
risposta data 14.03.2012 - 19:42
fonte

Leggi altre domande sui tag