Quali potrebbero essere alcune insidie nell'introduzione di una guida di stile e di un software di generazione di documentazione in un team di sviluppo?

Elementi per prendersi cura del processo e punto di vista culturale:
1. Garantire che le aspettative siano ben definite per ciò che dovrebbe essere il contenuto nella documentazione È importante definire che cosa dovrebbe essere scritto al termine della documentazione. Molte volte è sorprendente, ma le persone fanno ipotesi interne. I commenti inutili sono altrettanto negativi dei commenti.

2. La documentazione specifica dell'API non è in genere tutto
Molto spesso le documentazioni specifiche dell'API sono ideali per l'integrazione tra modulo e modulo black-box e consentono l'integrazione di sistemi complessi man mano che evolvono. Tuttavia, non sostituisce elementi chiave della documentazione come l'architettura generale, i progetti dettagliati o i design dei moduli, gli algoritmi, le funzionalità e le regole aziendali.

3. Assicurati che le persone comprino prima di applicarlo.
Il vero successo in qualsiasi processo è raggiunto solo quando c'è un impegno da parte delle persone per raggiungerlo. Potrebbe essere possibile dichiararlo come una politica e la gente potrebbe persino seguire verbatim per il gusto di farlo, ma non porterà frutti a meno che non sia fatto con il giusto spirito.

4. Coinvolgere il coinvolgimento e l'accordo delle persone prima di congelare lo standard esatto
Codificare i porcili aiuta sempre; e nessuno lo negherebbe. Tuttavia, richiede una modifica quando c'è una differenza tra ciò che segue personalmente e ciò che dice la politica. Quindi è meglio vedere ciò che la maggior parte delle persone è già in forma e definire le regole dove ci sarebbe meno danno. Inoltre, quando le persone vedono che è stata selezionata una certa linea guida di programmazione a causa del pensiero di maggioranza, è più probabile che accettino il cambiamento piuttosto che le regole imposte da un comitato.

5. Monitorare e adattare
Niente è perfetto il primo giorno quando inizia. Tieni alcune aspettative di base su cosa ti aspetteresti e monitora se le cose stanno accadendo in quel modo. Quando le cose non vengono tracciate, anche i buoni successi iniziali svaniscono.

** Per ulteriori Vedi questo

@ La risposta di Dipan copre i punti principali, ma c'è una cosa che devi fare con questo tipo di cambiamento culturale: iniziare in piccolo e sperimentare. Inizia con un progetto molto piccolo. Uno con persone che hai già dalla tua parte. Persone che amano documentare, usare strumenti di documentazione e più in generale provare cose nuove. Fai in modo che eseguano il debug del processo e chiedi loro di scrivere feedback. Una volta che hai lavorato con 2-3 programmatori, puoi provare a portare la modifica.

Potrebbe essere necessario del tempo, ma è necessario per definire esattamente quali sono i tuoi bisogni e se il tuo progetto si adatta bene al tuo ambiente (gli strumenti sono facili da configurare e gestire? la gente sta davvero usando il doc? processo di scrittura del documento aiuta le persone a formulare la loro idea? vuoi che altra squadra acceda alla tua documentazione? etc)

Se hai il budget, assumerei uno scrittore. Siamo definiti programmatori e possiamo assumere la proprietà del progetto. Sto lavorando con una società dell'area di Seattle che sta lavorando su Android e ha problemi simili. Una guida di stile non è una cattiva idea, ma raccomanderei vivamente di dare esempi concreti di buoni documenti. Vorrei anche leggere leggermente con feedback. Un feedback troppo negativo scoraggerà solo coloro che sono già reticenti ad esporre le loro capacità di scrittura meno che esemplificative.

Doug