ENTRIES TAGGED "documentation"
Is commenting your code a waste of time, or programmer gold?
Ask any developer what programming task they enjoy least, and odds are you’ll hear “documentation” as an answer. After all, you came here to write code, didn’t you? Who wants to write boring text about the code? In fact, documentation is the grease that keeps the development process moving — good documentation benefits your co-workers, the users, and maybe even you. And the most basic form of documentation is the comments in your program itself.
Can explanation contribute to technology creation?
“If you’re explaining, you’re losing.”
That gem of political wisdom has always been hard for me to take, as, after all, I make my living at explaining technology. I don’t feel like I’m losing. And yet…
It rings true. It’s not that programs and devices shouldn’t need documentation, but rather that documentation is an opportunity to find out just how complex a tool is. The problem is less that documentation writers are losing when they’re explaining, and more that creators of software and devices are losing when they have to settle for “fix in documentation.”
I was delighted last week to hear from Doug Schepers of webplatform.org that they want to “tighten the feedback loop between specification and documentation to make the specifications better.” Documentation means that someone has read and attempted to explain the specification to a broader audience, and the broader audience can then try things out and add their own comments. Writing documentation with that as an explicit goal is a much happier approach than the usual perils of documentation writers, trapped explaining unfixable tools whose creators apparently never gave much thought to explaining them.
It’s not just WebPlatform.org. I’ve praised the Elixir community for similar willingness to listen when people writing documentation (internal or external) report difficulties. When something is hard to explain, there’s usually some elegance missing. Developers writing their own documentation sometimes find it, but it can be easier to see the seams when you aren’t the one creating them.
The past, present, and future of Dell's project
Barton George (@barton808) is the Director of Development Programs at Dell, and the lead on Project Sputnik—Dell’s Ubuntu-based developer laptop (and its accompanying software). He sat down with me at OSCON to talk about what’s happened in the past year since OSCON 2012, and why he thinks Sputnik has a real chance at attracting developers.
Key highlights include:
- The developers that make up Sputnik’s ideal audience [Discussed at 1:00]
- The top three reasons you should try Sputnik [Discussed at 2:46]
- What Barton hopes to be talking about in 2014 [Discussed at 4:36]
- The key to building a community is documentation [Discussed at 5:20]
You can view the full interview here:
Cody Lindley on finding your way through a popular and powerful language
- Don’t be down on jQuery users (at 2:03)
- Are buffers between your code and browser APIs necessary? (at 9:17)
- Running browser tests on the DOM (at 11:08)
- Needing more focused in-depth documentation (at 12:57)
His closing – “we need to do a better job communicating with the bulk of developers out there” – sounded just right to me.
You can view the entire conversation in the following video:
Part of a series about efforts by VoIP Drupal collaborators to find the right media and tools with which to promote a small, little known software project.