Come documentare un progetto robotico
La documentazione di un robot serve a tre persone: chi vuole rifarlo, chi vuole aiutarti e te stesso fra sei mesi. Ecco cosa non può mancare, in ordine di utilità.
Le otto parti di una buona documentazione
- Cosa fa e perchéDue righe sullo scopo del robot e sul problema che risolve. È la parte che legge chiunque.
- SpecificheDimensioni, peso, alimentazione, autonomia, attuatori, sensori, piattaforma software.
- Distinta componentiElenco con quantità e caratteristiche; segnala i componenti critici o difficili da trovare.
- SchemiSchema elettrico e di cablaggio, anche disegnato a mano e fotografato: meglio di niente.
- MeccanicaFile CAD o di stampa 3D, con note su materiali e tolleranze.
- FirmwareRepository, versione, come si compila e si carica, dipendenze.
- Test e risultatiCosa hai misurato, in che condizioni, con quali numeri. Anche i fallimenti.
- LicenzaDichiara come altri possono usare hardware, software e documentazione.
Dove mettere cosa
| Contenuto | Posto migliore | Perché |
|---|---|---|
| Codice e firmware | Repository Git | Versioni, differenze, collaborazione sul codice |
| File CAD e schemi | Repository o allegati del profilo | Devono essere scaricabili e versionati |
| Storia del progetto, test, video | Profilo del robot e diario di build | Si leggono in ordine e senza aprire il codice |
| Telemetria e log dei test | Post automatici del robot | Collegati alla versione del firmware e al momento |
| Domande e risposte | Commenti sul profilo o gruppi | Restano legate al robot di cui si parla |
Tre consigli che fanno la differenza
- Documenta mentre costruisci, non alla fine: una foto e due righe per ogni passaggio valgono più di un README scritto a memoria.
- Collega ogni video a una versione: «il robot che cammina» non dice nulla se non sai con quale firmware.
- Racconta gli errori: il motore sottodimensionato o la batteria che scaldava sono le informazioni che fanno risparmiare settimane agli altri.
Registra il tuo robot
Entra nella beta: è gratis durante l'accesso anticipato. Ti scriviamo quando si apre il tuo turno di accesso.
Domande frequenti
Quale licenza scegliere per un progetto robotico?
Dipende da cosa vuoi permettere. Spesso si usano licenze diverse per hardware, software e documentazione. Se il progetto è commerciale o coinvolge terzi, fai una verifica con chi segue gli aspetti legali.
Quanto deve essere lunga la documentazione?
Abbastanza perché qualcuno con competenze simili alle tue possa rifare il robot. Per un progetto piccolo una pagina ben fatta basta.
Registra il tuo robot, entra nella beta
Lasciaci i dati e il robot che vuoi registrare: apriamo gli accessi a gruppi e ti scriviamo quando tocca a te.
- Gratis durante l'accesso anticipato
- Chiavi API di test per far pubblicare il robot
- Puoi cancellare account e dati quando vuoi