Personal tools

documentation

Jan 15, 2015

plone.api e documentazione: le linee guida del buon plonista

Scegliere la strada giusta può essere difficile a volte

plone.api e documentazione: le linee guida del buon plonista

Per non perdersi nel mare di possibilità implementative e scegliere sempre la strada giusta, basta seguire le linee guida che la comunità (finalmente) ci offre.

Si sa, il mondo è bello perché è vario, soprattutto nella programmazione: esistono mille modi diversi per risolvere un problema.

Un giorno Alice arrivò ad un bivio sulla strada e vide lo Stregatto sull'albero.
- "Che strada devo prendere?" chiese.
La risposta fu una domanda:
- "Dove vuoi andare?"
- "Non lo so", rispose Alice.
- "Allora, - disse lo Stregatto - non ha importanza".

Il lato positivo di questa libertà è che ognuno può implementare la soluzione come meglio crede.
Può capitare quindi che a seconda dell'umore, delle preferenze personali, o anche solo del tempo a disposizione (quante volte sarà capitato di avere tempi di sviluppo troppo serrati e scrivere del gran spaghetti code solo per poter concludere il lavoro) il risultato prodotto sia estremamente vario, ma funzioni comunque correttamente.

Il risvolto della medaglia, però, è che se si lavora in gruppo o in una comunità dove tutti possono leggere e attingere dal codice scritto da altri, ci si può trovare di fronte a codice incomprensibile: in questi casi il focus sul risultato finale non basta!
Se non si segue una certa linea di condotta, quello che si produce potrebbe risultare poco chiaro o troppo complicato e quindi generare confusione in chi non ha scritto direttamente quel codice. Soprattutto se chi legge non è un esperto e ha bisogno di capire qual'è la strada migliore da seguire.

read more

Oct 08, 2014

Zeal: documentazione sempre disponibile per il tuo lavoro

be zealous

Zeal: documentazione sempre disponibile per il tuo lavoro

Filed Under:

Come fare se nel bel mezzo di un problema, con la necessità di trovare la documentazione per risolverlo, non c'è rete e non possiamo rivolgerci a San Google?

Spesso la documentazione ufficiale di un prodotto non è la prima cosa che si va a vedere quando si cerca una soluzione a un problema specifico.

Una ricerca fatta con buone parole chiave di solito ci porta a navigare siti come stackoverflow.com molto più di quello che navighiamo altri siti come docs.python.org o www.sqlalchemy.org o altri ancora.

La possibilità di cercare documentazione in effetti è la cosa che mi manca di più quando non ho a disposizione una connessione a internet, evento raro ma non impossibile.

read more

May 30, 2014

How to write a good documentation - The big Plan

A room without books is like a body without a soul (Cicero)

How to write a good documentation - The big Plan

Earlier this year I had a perfect chance to participate to a sprint where the organization of documentation was the main purpose. Here it is what I learned

From ideas to reality

As you may know, what leads an open source project to the glory it's a well-written, clear and accessible documentation. This is more and more true as we are leaving the first era of internet where the technology was the king and we are entering the era where technology is just a tool that provides features and everything is more black boxed.

read more