Come si scrive direttamente alla documentazione del punto senza sembrare trascurati e informali?

Q: How do I write documentation in simple plain English that is of actual benefit without looking sloppy?

La documentazione dovrebbe essere creata per i lettori. Gli elementi importanti includono

• Contenuto: il contenuto della documentazione deve essere mirato alle informazioni richieste dal / ai lettore / i. Pensa ai tipi di attività per cui i lettori useranno la tua documentazione. Assicurati che i contenuti della tua documentazione siano pertinenti per loro e fornisci tutte le informazioni necessarie. Mentre impari cose sul sistema che stai documentando, prendi nota degli elementi che ti hanno richiesto più tempo del solito per capire o che ritieni siano contro-intuitivi. Questa è un'informazione che dovrebbe essere presente nel documento.
• Organizzazione e coesione: i contenuti del documento devono essere organizzati in modo logico. Ad esempio, per supportare attività basate sulle attività, le attività dovrebbero essere organizzate nell'ordine in cui il lettore le eseguirà. Per documentare un sistema, fornire introduzioni che forniscano una panoramica del sistema e di come i principali componenti / sottosistemi interagiscono prima di entrare nei dettagli su come funzionano i singoli pezzi. Se l'organizzazione ha un wiki o un simile sistema di gestione dei contenuti, considera l'utilizzo di questo per la documentazione. In caso contrario, fai lobby per avviare un tale sistema e ottenere supporto dal team con cui stai lavorando.
• Comprensibilità: usa solo termini che la maggior parte dei tuoi lettori capirà. Evita il gergo. Se lo usi, fornisci la definizione del termine. Definisci tutti gli acronimi e le abbreviazioni al primo utilizzo.
• Leggibilità: utilizza la grammatica corretta. Una persona non tecnica interessata dovrebbe essere in grado di comprendere il materiale.
• Contesto: come hai osservato, le informazioni dettagliate che non sono inserite in un contesto appropriato possono essere difficili da comprendere. Fornisci materiale introduttivo che identifica brevemente tutti i componenti chiave, i livelli, le API, i pacchetti, ecc. Che comprendono il sistema che stai documentando.

Q: I find it difficult in areas such as outlining a system's flaws without coming off as judgmental, but still emphasize the severity of how detrimental some of the flaws are.

Fai pratica con la documentazione di egoless . Se nel sistema sono presenti elementi di design scomodi, hai il dovere di evidenziare qualsiasi informazione aggiuntiva, cura o passaggi di cui un lettore ha bisogno di sapere, ma non giudicare l'imbarazzo in sé. Evita aggettivi come "idiota". Ad esempio, supponiamo che ci siano diversi file che devono essere modificati per effettuare una semplice modifica della configurazione. Do - Disporre i passaggi richiesti. Non - sprecare testo incolpando i designer originali per la loro mancanza di lungimiranza e / o abilità mentali.