Gestió de documentació
Pràctica sobre gestió i generació de documentació tècnica mitjançant Sphinx.
Objectius
- Conèixer els aspectes més problemàtics de la gestió de documentació tècnica i, específicament del programari.
- Aprendre a usar Sphinx per generar i mantenir la documentació associada a un projecte de programari.
Material
Lliurables
Cal lliurar
- Tarfile de la documentació dels mòduls "terme" i "ct", del projecte de curs d'INF. Aquesta documentació ha de tenir:
- Una descripció del projecte i dels seus mòduls.
- Una descripció de cada mòdul. A tal efecte cal documentar correctament el mòdul usant la sintaxi reST i després incorporar de forma automàtica aquesta documentació usant les construccions necessàries de Sphinx.
Es valorarà
- L'organització i claredat de la documentació.
- La correcció de redacció, sintàctica i ortogràfica.
- Que la documentació estigui escrita en anglès (tot i no ser obligatori)
Referències
- Entrada de la wikipèdia sobre redacció tècnica.
- Entrada de la wikipèdia sobre documentació de programari.
- Pàgina del Working group 2 de ISO/IEC sobre Documentació de programari.
- Documentació de Sphinx.
- Tutorial sobre Sphinx que val la pena llegir-se en un moment.
- Exemple de documentació, que explica de forma resumida com fer servir Sphinx.
L'escriptura de documentació tècnica no deixa de ser un tipus de redacció que, com a tal, està relacionada amb la tècnica de la redacció de documents en general. En aquest àmbit les següents referències poden ser interessants:
- David A. McMurrey, Steps to structure and coherence: Advanced writing strategies
- David A. McMurrey, Sentence style problems