Documentation for Fun and Profit
Last week at the London Perl Workshop, I gave my first ever talk. 20 minutes on the subject of documentation. I'm pleased to say it went very well, and I've had some fantastic feedback from everyone who saw it.
I thought the wider perl community would appreciate having a look at my slides. As always, it would make more sense to hear me talking - but this gives a good idea as to what the talk is about.
If anyone wants to invite me to speak at exotic locations around the world, I am available ;)
I blog about Perl. I'm on Twitter, GitHub, and everywhere else as @LoonyPandora.
Except the CPAN, where I'm JAITKEN. Silly character limits...
I have found this talk very good at LPW2012, thank you LoonyPandora.
I have gained from listening to this talk :
- A refreshing reminder of what a good documentation is and why is really matters.
- Several ways to "cheat" and keep documenting and easy and natural task.
- A tool : I am going to try your Pod::HTML5::Browser module (i had forgotten about it up until now).
- Reasons for writing documentation first: Documentation Driven Development.
I have started to do it and enjoy it. My documentation is now better and so is my code: because documenting first makes me take the time to think properly about my APIs.
- Gain time : a good documentation saves me lots of searching through my code to try and remember what it was that i did, and how. A few well chosen words are clearer than a hundred lines of code.
In two words LoonyPandora : Thank you.
If i have the occasion i might even come and listen to your talk again.
I must say, Pod::HTML::Browser misses some documentation (i struggled a bit to set it up); but the result is nice. And i don't even have it all : i didn't find the favicon and touch icons images anywhere in /img. Did i miss something?
Will the search bar do anything more than what the browsers can do?