Scrivere documentazione efficace per Discourse

[maiki]

Ciao Simon!

@simon

@Discourse

Usa contrazioni: it’s, you’ll, you’re, we’re, let’s

Oltre a evitare gli idiomi, ho sempre evitato di usare contrazioni nella documentazione. Pensavo che rendessero più difficile la comprensione per i lettori non anglofoni/non occidentali. L’inglese è una lingua strana.

Stavo per vedere come sarebbe andata, ma sì, sono lo stesso, cerco di evitare le contrazioni.

@simon

@Discourse

Usa parole di transizione come inoltre, sebbene, quindi, e pertanto

inoltre?

Hahah, sì… non userò nessuna di quelle parole nella documentazione, per non rivelare il mio .

@simon

Potrebbe valere la pena usare un nome segnaposto coerente per fare riferimento ai siti Discourse. Forse discourse.example.com? C’è della documentazione qui che si riferisce al sito Discourse come sitename.com. Mi ha davvero confuso.

Certamente: Example Domains

@simon

Per quanto apprezzi non avere più un sacco di argomenti di documentazione a me attribuiti, usare Discourse come autore di tutti gli argomenti di documentazione del team sembra un po’ freddo.

Ciò che ha reso di nuovo divertente scrivere per me è stato il consiglio di cercare modi per mettere un po’ di sé in ciò che si scrive. Potrebbe essere qualsiasi cosa, il tuo tono di voce, i tuoi hobby, qualsiasi cosa… Questo è un po’ l’opposto di ciò che viene raccomandato qui.

Questo è il punto che sono venuto a discutere!

Abbiamo avuto un sacco di avanti e indietro su questo, ed ero felice di vederlo incluso nella guida di stile per impostazione predefinita.

Ecco perché penso che sia importante: produrre documentazione deve essere accessibile al maggior numero possibile di membri della nostra community, inclusi (soprattutto?) i membri del nostro team Discourse.

Discourse è un software di discussione sociale. E una parte della documentazione è davvero una conversazione continua. Se sto condividendo una pratica su come inserisco i membri nella mia community, vorrei essere presentato come il “proprietario” di quell’argomento, in modo da poter rispondere alle domande ed espandere l’argomento.

D’altra parte, se un cliente chiede di una funzionalità che non abbiamo mai spiegato, vorrei poter utilizzare la guida di stile e produrre documentazione utile e generale, che ritengo essere il proprietario dell’argomento presenti più inerzia alla pubblicazione.

Inoltre, se produciamo documentazione al di fuori di Discourse (un’integrazione o la produzione da commenti di codice o altro), avere un “utente di documentazione” è probabilmente più facile come dettaglio di implementazione.

Non penso che questa guida impedirà alle persone di infondere la loro voce e personalità, e di ospitare la discussione. Ma sarebbe fantastico se aiutasse più persone a entrare nella pratica della documentazione, che altrimenti non lo farebbero (e poi potremo spingerle a essere più personali!)