You know, precise and correct documentation is the one kept in synch with the source code automatically.
There are many ways of doing that, many kinds of documentation. Here I’ll show you how to publish content in GitHub Pages after a successful build. In this case, the content is a API specification generated when running acceptance tests.
How to do it?
- Put the content you want to be published in the /docs dir
- Go to Settings, find the GitHub Pages section, and select Source to master branch /docs folder, then press Save
- Push it to master.
The content in the /docs will be available at
eHelp is configured to put its generated specs in the /docs folder. Every time we push to master, its GitHub Page gets updated. This way, its specs are always published and always in sync.
The Past – In Case You Are Curious
(It’s nice to see that things are getting simpler.)
Not so long ago, I wrote a post (Tip #1) explaining how to achieve the same result using Travis CI and some scripting help. This little project is configured the old way: see travis.yml and update-gh-pages.sh files.
You can find more information at GitHub help pages:
(Read the english version here.)
Ho conosciuto un programmatore in Italia che stava sviluppando una applicazione per aiutare un Mercato dei Salumi e Formaggi (è così che si chiama il negozio) a meglio servire i suoi clienti.
In questo articolo provo a spiegare come lui ha riuscito a capire cos’era importante agli utenti dell’app e quali funzionalità dovrebbero essere presenti nel primo rilascio in produzione.
Questo mio collega era impegnato a sviluppare in modo incrementale basato sulle esigenze del cliente. In altre parole:
- rilasciare una nuova versione in produzione periodicamente (diciamo ogni due settimane) con nuove funzionalità, correzioni di bug e eventuali modifiche richieste dall’utente
- permettere all’utente di decidere (e aiutarlo a decidere) quali funzionalità devono essere consegnati prima
- scrivere tests in modo a guidare il design e la implementazione del software (TDD).
Continue reading “Draghi, Unicorni e Titani* – Un Racconto di un Sviluppatore Agile”
Now that we have a very good idea about what app X is all about, we can finally start writing tests and implementing functionalities. We feel very good because we are a modern agile team, with TDD, pair programming, CI, even Kanban! There is a lot of work to do. And we mean business. But how long do we take to release new features? How long do we take to release the very first one?
Delivering the first functionality involves a lot of work exactly because it’s the first time the app is going to be released in production. Just to mention a few tasks:
- choosing all the essential libraries, tools, preferred frameworks and make them work together;
- set up repository, continuous integration, database in the dev environment*;
- prepare the staging environment*;
- production environment;
- automate deploy.
It’s common to have dev-teams developing code right after completing the 2nd or 1st task in the list, and measuring progress somehow. It certainly feels like a lot of progress is happening there (and we like to feel we are productive developers), though none of that is useful since customers can’t use the app yet.
Continue reading “Iteration Zero & The Very First Release”
(Leggi la versione italiana qui.)
I’ve met a software engineer in Italy that was developing an application to help a Mercato dei Salumi e Formaggi to better serve their customers.
Here I tell how he managed to understand what was important to the users and which functionalities should be delivered first.
My colleague was committed to develop incrementally based on his client needs. That translates to:
- release a new version of the application in production periodically (let’s say two weeks) with new features, bug fixes and possible changes requested by the user
- let the user decide (and help him to decide) which features must be delivered first
- let tests guide software design and implementation.
Continue reading “Dragons, Unicorns and Titans* – An Agile Software Developer Tail”