"documentation" entries

The book sprint

Not just for code anymore

OpenStack Operations GuideDo you really want a technical book for your project? Does your community need to provide more helpful docs to support even more users? Does your community have a lot of knowledge they need to get out of heads and into bits and bytes? Do you have a good mix of technical experts and technical writers and users who would enjoy each other’s company for a week of hard work?

If the answer is yes, then consider a book sprint. If you’re in the open source world, you may have heard of a code sprint. A book sprint is a similar event, with an intense collaborative authoring session time boxed by a few days or a week. People get together typically in person to author and complete a book in a week.

Generally speaking it’s best if you have an idea of the scope and audience for the book prior to holding the sprint. These discussions can take place on line, such as on a mailing list or in a wiki page or Etherpad. You can also meet with future collaborators regularly, but understand, the first day of your sprint your book will certainly take shape. As book sprinter Adam Hyde says, “While you may not know the exact book you want when you go into the sprint, by the end you will have the book you need.”

For the OpenStack Operations Guide, we held a five-day book sprint in February 2013. OpenStack releases every April and October, and this timing was nearly halfway between two release dates. With Adam as our facilitator, seven authors agreed to work together and we nervously awaited our fate. We asked, “Could we complete a book in a week?”

Read more…

Comment: 1

Fun, functional, and teachable?

Can Elixir bring functional programming to a much wider audience?

I was delighted to talk with Dave Thomas, co-founder of the The Pragmatic Programmers and author of their in-progress Programming Elixir. I’m writing Introducing Elixir for O’Reilly, and we both seem to be enjoying the progress of the language. Read more…

Comment

Formulating Elixir

Simon St. Laurent and Jose Valim explore a new functional programming language

I was delighted to sit down with Jose Valim, the creator of Elixir, earlier this month at Erlang Factory. He and Dave Thomas had just given a brave keynote exploring the barriers that keep people from taking advantage of Erlang’s many superpowers, challenging the audience with reminders that a programming environment must have reach as well as power to change the world.

Elixir itself is a bold effort to bring Erlang’s strengths to a broader group of developers, adding new strengths, notably metaprogramming, along the way.

Watching Elixir grow has been a unique experience for me. I’ve seen other languages (JavaScript and XSLT) emerge, but Elixir combines solid foundations on prior (Erlang) work with a remarkably open conversation about how to structure the language. Jose tries things and asks for feedback, takes suggestions well, and values questions about how best to make the language accessible. Even without a standards organization, the process has remained open, stable, and productive.

Whether you’re interested in Elixir itself or just in the challenges of creating a new combination in a world filled with past experiments, it’s well worth listening to Jose Valim.

  • We’ve had functional programming since 1959 – why the burst of interest now? [2:10]
  • Moving from Ruby to Erlang “making Rails thread-safe, that was my personal pain-point” [3:13]
  • “Every time I got to study more about the VM, the tooling and everything it provides, my mind gets blown.” [6:12]
  • Why Elixir started, and how it’s changed as Jose learned more. [10:08]
  • Integrating new Erlang features (R17 maps) into Elixir. [15:43]
  • When can you use Elixir in production? [18:07]

I’m looking forward to seeing a lot more Elixir, even as I need to catch up on updating Introducing Elixir. I’m not sure it will conquer the world immediately, but it will certainly leave its mark.

Comment

The art of commenting

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.

Read more…

Comment: 1

Documentation as Testing

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.
Read more…

Comments: 4

Will Developers Move to Sputnik?

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:

Read more…

Comment

Learning Paths for JavaScript

Cody Lindley on finding your way through a popular and powerful language

Everyone learns and teaches JavaScript their own way, but Cody Lindley (@codylindley) has spent a lot of time with a lot of different kinds of learners. He made the jQuery Cookbook happen, finding and managing contributors as well as making a large contribution himself, and he’s a regular at JavaScript conferences.

O’Reilly recently published his JavaScript Enlightenment and DOM Enlightenment, so it seemed like a good time to talk about how developers find their way through the many choices JavaScript offers.

Highlights include:

  • JavaScript developer? Or front-end engineer? Websites? Or applications? (at 0:52)
  • Don’t be down on jQuery users (at 2:03)
  • JavaScript objects are different, and critical (at 4:07)
  • The varying degrees of genius in JavaScript libraries (at 7:17)
  • 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:

Comments: 3

Promoting and documenting a small software project: VoIP Drupal update

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.

Comments: 3

Documentation strategy for a small software project: launching VoIP Drupal introductions

VoIP Drupal is a window onto the promises and challenges faced by a new open source project, including its documentation. A meeting at at MIT this week worked out some long-term plans for firming up VoIP Drupal's documentation and other training materials.

Comments: 2

Wrap-up from FLOSS Manuals book sprint at Google

Mixtures of grassroots content generation and unique expertise have existed, and more models will be found. Understanding the points of commonality between the systems will help us develop such models.

Comments: 3