"documentation" entries

Four short links: 25 February 2016

Four short links: 25 February 2016

Security Advice, Common Deep Learning Interface, React Text Editing, and Sexy Docs

  1. Free Security Advice (grugq) — chap wearies of handing out security advice, so gathers it and shares for all.
  2. TensorFuseCommon interface for Theano, CGT, and TensorFlow.
  3. Draft.jsa framework for building rich text editors in React, powered by an immutable model and abstracting over cross-browser differences.
  4. Dexya free-form literate documentation tool for writing any kind of technical document incorporating code. Dexy helps you write correct documents, and to easily maintain them over time as your code changes.
Four short links: 13 August 2015

Four short links: 13 August 2015

Learning Style, Artisinal Cash, Docs at Scale, and Homophily Research

  1. Elements of Style: Learning Perceptual Shape Style Similarity — code and data for research that helps perceive stylistic similarity between objects that transcends structure and function. For example, we can see a common style such as “Danish modern” in both a table and chair, though they have different structures. Until now, machines have found it difficult to do the same. (That quote cribbed from the phys.org writeup) Our new AI overlords may be cruel and heartless, but they’ll be able to tell Danish Modern from Shaker.
  2. The Advent of Artisinal Cash (NY Times) — details the rise of local physical currency around the world. Nonetheless, the use of traditional paper money is clearly on the wane. Perhaps these smaller, more attractive artisanal paper notes are merely last bursts of glory before it disappears entirely. Though as Mr. Deller, the artist behind the latest Brixton pound, said, “As long as there are drug deals and criminality, there’ll be a need for cash.”
  3. Documentation at Scale1. Acknowledge that brute force doesn’t work; 2. Make documentation a first class citizen; 3. Make documentation executable; 4. Track the intent.
  4. Exposure to Ideologically Diverse Information on Facebook (Facebook Research) — Friends shared substantially less cross-cutting news from sources aligned with an opposing ideology. People encountered roughly 15% less cross-cutting content in news feeds due to algorithmic ranking and clicked through to 70% less of this cross-cutting content. Within the domain of political news encountered in social media, selective exposure appears to drive attention.
Four short links: 16 June 2015

Four short links: 16 June 2015

Accessibility Testing, Time-Series Graphing, NO BUBBLE TO SEE HERE, and Technical Documentation

  1. axe — accessibility testing of web apps, so you can integrate accessibility testing into your continuous EVERYTHING pipeline.
  2. metrics-graphics — Mozilla Javascript library optimized for visualizing and laying out time-series data.
  3. US Tech Funding: What’s Going On? (A16Z) — deck eloquently arguing that this is no bubble.
  4. Teach Don’t Tellwhat I think good documentation is and how I think you should go about writing it. Sample common sense: This is obvious when you’re working face-to-face with someone. When you tell them how to play a C major chord on the guitar and they only produce a strangled squeak, it’s clear that you need to slow down and talk about how to press down on the strings properly. As programmers, we almost never get this kind of feedback about our documentation. We don’t see that the person on the other end of the wire is hopelessly confused and blundering around because they’re missing something we thought was obvious (but wasn’t). Teaching someone in person helps you learn to anticipate this, which will pay off (for your users) when you’re writing documentation.

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…

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…

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.

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…

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…

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…

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: