Newer posts are loading.
You are at the newest post.
Click here to check if anything new just came in.

November 08 2013

July 12 2013

DevDocs ❝Provides access to the following API documentations : HTML, CSS, DOM, DOM Events,…


Provides access to the following API documentations: HTML, CSS, DOM, DOM Events, JavaScript and jQuery. The material comes from the usual places (Mozilla Developer Network et al.), but has been consistently and pleasantly styled and provides a slick search user interface. Upcoming feature: offline capability.

#HTML #CSS #DOM #JavaScript #jQuery #documentation

Sponsored post

June 29 2013

13 points que les gens détestent sur la documentation de votre projet libre - Framablog

13 points que les gens détestent sur la documentation de votre projet libre - Framablog

Qu'il s'agisse de son code ou de son utilisation, la faiblesse de la documentation d'un logiciel libre est souvent montrée du doigt.

Voici, selon Andy Lester, 13 défauts ou lacunes communément rencontrés, qui sont autant d'écueils que l'on peut corriger avec un minimum d'efforts aujourd'hui pour un précieux temps gagné demain.


April 06 2012

Promoting and documenting a small software project: VoIP Drupal update

Isn't the integration of mobile phones and the Web one of the hot topics in modern technology? If so, VoIP Drupal should become a fixture of web development and administration. I have been meeting with leaders of the project to help with their documentation and publicity. I reported on my first meeting with them here on Radar, and this posting is one of a series of follow-ups I plan to write.

Immediate pressures

When Leo Burd, the lead developer of VoIP Drupal, first pulled together a small cohort of supporters to help with documentation and promotion, only three weeks were left before DrupalCon, the major Drupal annual conference. Leo was doing some presentations there, and the pressing question was what users would want in order to get interested in VoIP Drupal, learn more about it, and be able to get started.

Leo was indefatigable. He planned to get some new modules finished before the conference, but in addition to coding and preparing his own presentations, he wanted to address the lack of introductory materials because it might get in the way of enticing new users to try VoIP Drupal.

In the end, Leo led a webinar to drum up interest. The little group of half a dozen self-selected fans reviewed his slides, sat in on a preview, and helped whip it into a really well-focused, hard-hitting survey. This webinar had 94 participants from 19 countries and more than 40 companies.

Michele Metts, a non-profit activist and Drupal consultant, also stepped up to create slides and lead webinars with slides explaining VoIP Drupal basics.

Slide from a VoIP Drupal webinar
Slide from a VoIP Drupal webinar

Although we agreed that many parts of the system needed more documentation, it was a more effective use of time at this point to do webinars. VoiP Drupal has many interactive aspects that are best shown off through demonstrations. As I'll explain, documentation would require more resources.

Perceptions and challenges

Responses to the webinar and to Leo's DrupalCon presentation helped us understand better what it would take to win more adherents to this useful tool. Leo reported that few people knew of the existence of VoIP Drupal, but that when they heard of it, they assumed it would be expensive. His impression was that they knew traditional PBX systems and didn't realize how much more low-cost and light-weight VoIP is.

In my opinion, Web administrators (and many content providers) still see the Web and the telephone as separate worlds, never to meet. This despite the increasing popularity of running queries and Internet apps on mobile devices. We have to address server-side apathy. There should come a day when the things VoIP Drupal does are taken for granted: people leaving phone numbers on Web sites to receive SMS or voice updates, pressing Web buttons on their cell phones to get an interactive voice menu, etc.

The versatility of VoIP Drupal gives it fantastic potential but makes it harder to explain in an elevator speech. The ways in which voice can be integrated with the Web are nearly infinite. In addition, two distinctly different settings can benefit from VoIP. One consists of highly structured corporate sites, which can use VoIP Drupal for such typical bureaucratic tasks as offering interactive voice menus and routing customers to extensions. The other consists of sites serving underdeveloped areas, where people are more adept at using their phones than dealing with text-based Web sites. We need different pitches for each potential user.

Finally (and here my training as an editor pokes in), there are a number of different audiences who need to understand VoIP Drupal on different levels. Content providers need to understand what it can do and see models for incorporating it into their Drupal sites. Administrators need to understand how to find scripts and offer them to content providers. And programmers need to learn how to write fresh scripts. We also want to attract open source developers who could help enhance and maintain VoIP Drupal. There is even a tool called Visual VoIP Drupal that reduces the amount of programming skill required to create a new script pretty close to a minimum--that creates yet another audience.

Documentation needs

My goal in joining the informal VoiP Drupal promotion team was to use this project as a test case for exploring what software projects do for documentation, and how they could do better.

A number of sites have successfully implemented VoIP Drupal, some of them in quite sophisticated ways, but you could call these the alpha developers or early adopters. They managed, for instance, to find the reference documentation that requires several clicks to access, and which I did not notice for weeks. And needless to say, they required no other documentation, because the tutorials are extremely rudimentary.

I think that VoIP Drupal documentation is typical of early software projects--and in fact better than many. Projects tend to toss the reader a brief tutorial, provide some examples with inadequate explanatory text, and finally dunk the reader in the middle of an API reference. The tutorial tends to be fragile, in the sense that any problem encountered by the reader (a missing step, a change in environment) leaves her in an unrecoverable state, because there is no documentation about the way the system works and its assumptions. And the context for understanding reference documentation is missing, so that it can be used only by experienced developers who have seen similar programs in other environments.

Useful VoIP Drupal documentation includes (these are examples):

Our team knew that more descriptive text was needed to pull together these pieces, but whoever wrote a document would need some intensive time with a core developer. This was unfeasible in the rush to get the software in shape for DrupalCon. I found out about the difficulties of producing documents first-hand when I decided to tackle Visual VoIP Drupal, which looked simple and intuitive. Unfortunately, there were a lot of oddities in its behavior, and the simplicity of the interface didn't save me from having to know some of the subtler and less documented aspects of VoIP Drupal programming, such as handling input variables.

In a recent teleconference, I asked a bunch of preliminary questions and got a better idea of what documentation already covers, as well as a starting point for doing more documentation.

Current documentation tasks, in my opinion, include:

  • Expand the tutorials to show more of the capabilities of VoIP Drupal.

  • Provide explanations of key topics, such as different ways to handle voice input, keyboard input, and the metainformation provided by VoIP Drupal about each call. The developers' provision of a simple scripting system on top of PHP, and even more the creation of Visual VoIP Drupal, demonstrates their commitment to reaching non-programmers, but we have to follow through by filling in the background they lack.

  • Create a few videos or webinars on Visual VoIP Drupal.

  • Make links to the reference documentation more prominent, and link to it liberally in the tutorials and background documents. The use of doc strings from the code is reasonable for reference documentation, because nobody is asking it to look pretty and we want to maximize the probability that it will stay up to date.

  • Ask the community for examples and case studies, and describe what makes each one an interesting use of VoIP Drupal.

There's plenty that could be done, such as describing how to integrate VoIP Drupal into existing PHP code (and therefore more fully into existing Drupal pages) but that can be postponed. Leo said he's "particularly interested in working with Micky and the rest this group in the creation of a Visual VoIP Drupal webinar, and one about things we can do with VoIP Drupal right out of the box, with no or minimum programming."

What motivates people like Michele and me to put so much time into this project? Certainly, Michele wants to promote a project that she uses in her own work so that it thrives and continues to evolve. I can use what I learn from this work to provide services to other open source communities. But beyond all these individual rewards is a gut feeling that VoIP Drupal is cool. Using it is fun, and talking about it is also fun. Projects have achieved success for more light-weight reasons.

February 17 2012

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. At O'Reilly, we've been conscious for some time that we lack a business model for documenting new collaborative projects--near the beginning, at the stage where they could use the most help with good materials to promote their work, but don't have a community large enough to support a book--and I joined VoIP Drupal to explore how a professional editor can help such a team.

Small projects can reach a certain maturity with poor and sparse document. But the critical move from early adopters to mainstream requires a lot more hand-holding for prospective users. And these projects can spare hardly any developer time for documentation. Users and fans can be helpful here, but their documentation needs to be checked and updated over time; furthermore, reliance on spontaneous contributions from users leads to spotty and unpredictable coverage.

Large projects can hire technical writers, but what they do is very different from traditional documentation; they must be community managers as well as writers and editors (see Anne Gentle's book Conversation and Community: The Social Web for Documentation). So these projects can benefit from research into communities also.

I met at the MIT Media Lab this week with Leo Burd, the inventor of VoIP Drupal, and a couple other supporters, notably Micky Metts of We worked out some long-term plans for firming up VoIP Drupal's documentation and other training materials. But we also had to deal with an urgent need for materials to offer at DrupalCon, which begins in just over one month.


One of the difficulties of explaining VoIP Drupal is that it's just so versatile. The foundations are simple:

  • A thin wrapper around PHP permits developers to write simple scripts that dial phone numbers, send SMS messages, etc. These scripts run on services that initiate connections and do translation between voice and text (Tropo, Twilio, and the free Plivo are currently supported).

  • Administrators on Drupal sites can use the Drupal interface to configure VoIP Drupal modules and add phone/SMS scripts to their sites.

  • Content providers can use the VoIP Drupal capabilities provided by their administrators to do such things as send text messages to site users, or to enable site users to record messages using their phone or computer.

Already you can see one challenge: VoIP Drupal has three different audiences that need very different documentation. In fact, we've thought of two more audiences: decision-makers who might build a business or service on top of VoIP Drupal, and potential team members who will maintain and build new features.

Some juicy modules built on top of VoIP Drupal's core extend its versatility to the point where it's hard to explain on an elevator ride what VoIP Drupal could do. Leo tosses out a few ideas such as:

  • Emergency awareness systems that use multiple channels to reach out to a population who live in a certain area. That would require a combination of user profiling, mapping and communication capabilities tend to be extremely hard to put together under one single package.

  • Community polling/voting systems that are accessible via web, SMS, email, phone, etc.

  • CRM systems that keep track (and even record) phone interactions, organize group conference calls with the click of a button, etc.

  • Voice-based bulletin boards.

  • Adding multiple authentication mechanisms to a site.

  • Sending SMS event notifications based on Google Calendars.

In theory you could create a complete voice and SMS based system out of VoIP Drupal and ignore the web site altogether, but that would be a rather cumbersome exercise. VoIP Drupal is well-suited to integrating voice and the Web--and it leaves lots of room for creativity.

Long-term development

A community project, we agreed, needs to be incremental and will result in widely distributed documents. Some people like big manuals, but most want a quickie getting-started guide and then lots of chances to explore different options at their own pace. Communities are good for developing small documents of different types. The challenge is finding someone to cover any particular feature, as well as to do the sometimes tedious work of updating the document over time.

We decided that videos would be valuable for the administrators and content providers, because they work through graphical interfaces. However, the material should also be documented in plain text. This expands access to the material in two ways. First, VoIP Drupal may be popular in part of the world where bandwidth limitations make it hard to view videos. Second, the text pages are easier to translate into other languages.

Just as a video can be worth a thousand words, working scripts can replace a dozen explanations. Leo will set up a code contribution site on Github. This is more work than it may seem, because malicious or buggy scripts can wreak havoc for users (imagine someone getting a thousand identical SMS messages over the course of a single hour, for instance), so contributions have to be vetted.

Some projects assign a knowledgeable person or two to create an outline, then ask community members to fill it in. I find this approach too restrictive. Having a huge unfilled structure is just depressing. And one has to grab the excitement of volunteers wherever it happens to land. Just asking them to document what they love about a project will get you more material than presenting them with a mandate to cover certain topics.

But then how do you get crucial features documented? Wait and watch forums for people discussing those features. When someone seems particularly knowledgeable and eager to help, ask him or her for a longer document that covers the feature. You then have to reward this person for doing the work, and a couple ways that make sense in this situation include:

  • Get an editor to tighten up the document and work with the author to make a really professional article out of it.

  • Highlight it on your web site and make sure people can find it easily. For many volunteers, seeing their material widely used is the best reward.

We also agreed that we should divide documentation into practical, how-to documents and conceptual documents. Users like to grab a hello-world document and throw together their first program. As they start to shape their own projects, they realize they don't really understand how the system fits together and that they need some background concepts. Here is where most software projects fail. They assume that the reader understands the reasoning behind the design and knows how best to use it.

Good conceptual documentation is hard to produce, partly because the lead developers have the concepts so deeply ingrained that they don't realize what it is that other people don't know. Breaking the problems down into small chunks, though, can make it easier to produce useful guides.

Like many software projects, VoIP Drupal documentation currently starts the reader off with a list of modules. The team members liked an idea of mine to replace these with brief tutorials or use cases. Each would start with a goal or question (what the reader wants to accomplish) and then introduce the relevant module. In general, given the flexibility of VoIP Drupal, we agreed we need a lot more "why and when" documentation.

Immediate preparations

Before we take on a major restructuring and expansion of documentation, though, we have a tight deadline for producing some key videos and documents. Leo is going to lead a development workshop at DrupalCon, and he has to determine the minimum documentation needed to make it a productive experience. He also wants to do a webinar on February 28 or 29, and a series of videos on basic topics such as installing VoIP Drupal, a survey of successful sites using it, and a nifty graphical interface called Visual VoIP Drupal. Visual VoIP Drupal, which will be released in a few weeks, is one of the new features Leo would like to promote in order to excite users. It lets a programmer select blocks and blend them into a script through a GUI, instead of typing all the code.

The next few weeks will bring a flurry of work to realize our vision.

October 21 2011

Wrap-up from FLOSS Manuals book sprint at Google

At several points during this week's documentation sprint at Google, I talked with the founder of FLOSS Manuals, Adam Hyde, who developed the doc sprint as it is practiced today. Our conversation often returned to the differences between the group writing experience we had this week and traditional publishing. The willingness of my boss at O'Reilly Media to send me to this conference shows how interested the company is learning what we might be able to take from sprints.

Some of the differences between sprints and traditional publishing are quite subtle. The collaborative process is obviously different, but many people outside publishing might not realize just how deeply the egoless collaboration of sprints flies in the face of the traditional publishing model. The reason is that publishing has long depended on the star author. In whatever way a person becomes this kind a star, whether by working his way up the journalism hierarchy like Thomas Friedman or bursting on the scene with a dazzling person story like Greg Mortenson (author of Three Cups of Tea), stardom is almost the only way to sell books in profitable numbers. Authors who use the books themselves to build stardom still need to keep themselves in the public limelight somehow. Without colorful personalities, the publishing industry needs a new way to make money (along with Hollywood, television, and pop music).

But that's not the end of differences. Publishers also need to promise a certain amount of content, whereas sprinters and other free documentation projects can just put out what they feel like writing and say, "If you want more, add it." Traditional publishing will alienate readers if books come out with certain topics missing. Furthermore, if a book lacks a popular topic that a competitor has, the competitor will trounce the less well-endowed book in the market. So publishers are not simply inventing needs to maintain control over the development effort. They're not exerting control just to tamp down on unauthorized distribution or something like that. When they sell content, users have expectations that publishers strive to meet, so they need strong control over the content and the schedule for each book.

But O'Reilly, along with other publishers across the industry, is trying to change expectations. The goal of comprehensiveness conflicts with another goal, timeliness, that is becoming more and more important. We're responding in three ways that both bring us closer to what FLOSS Manuals is doing: we put out "early releases" containing parts of books that are underway, we sign contracts for projects on limited topics that are very short by design, and we're experimenting with systems that are even closer to the FLOSS Manuals system, allowing authors to change a book at whim and publish a new version immediately.

Although FLOSS Manuals produces free books and gets almost none of its funding from sales (the funding comes from grants and from the sponsors of sprints), the idea of sprinting is still compatible with traditional publishing, in which sales are the whole point. Traditional publishers tend to give several thousand dollars to authors in the form of advances, and if the author takes several months to produce a book, we don't see the royalties that pay us back for that investment for a long time. Why not spend a few thousand dollars to bring a team of authors to a pleasant but distraction-free location (I have to admit that Google headquarters is not at all distraction-free) and pay for a week of intense writing?

Authors would probably find it much more appealing to take a one-week vacation and say good-bye to their families for this time than to spend months stealing time on evenings and weekends and apologizing for not being fully present.

The problem, as I explained in my first posting this week, is that you never quite know what you're going to get from a sprint. In addition, the material is still rough at the end of a week and has to absorb a lot of work to rise to the standards of professional publishing. Still, many technical publishers would be happy to get over a hundred pages of relevant material in a single week.

Publishers who fail to make documents free and open might be more disadvantaged when seeking remote contributions. Sprints don't get many contributions from people outside the room where it is conducted, but sometimes advice and support weigh in on some critical, highly technical point. The sprints I have participated in (sometimes remotely) benefited from answers that came out of the cloud to resolve difficult questions. For instance, one commenter on this week's KDE conference warned us we were using product names all wrong and had us go back through the book to make sure our branding was correct.

Will people offer their time to help authors and publishers develop closed books? O'Reilly has put books online during development, and random visitors do offer fixes and comments. There is some good will toward anyone who wants to offer guidance that a community considers important. But free, open documents are likely to draw even more help from crowdsourcing.

At the summit today, with the books all wrapped up and published, we held a feedback session. The organizers asked us our opinions on the sprint process, the writing tools, and how to make the sprint more effective. Our facilitator raised three issues that, once again, reminded me of the requirements of traditional publishing:

  • Taking long-term responsibility for a document. How does one motivate people to contribute to it? In the case of free software communities, they need to make updates a communal responsibility and integrate the document into their project life cycle just like the software.

  • Promoting the document. Without lots of hype, people will not notice the existence of the book and pick it up. Promotion is pretty much the same no matter how content is produced (social networking, blogging, and video play big roles nowadays), but free books are distinguished by the goal of sharing widely without concern for authorial control or payment. Furthermore, while FLOSS Manuals is conscious of branding, it does not use copyright or trademarks to restrict use of graphics or other trade dress.

  • Integrating a document into a community. This is related to both maintenance and promotion. But every great book has a community around it, and there are lots of ways people can use them in training and other member-building activities. Forums and feedback pages are also important.

Over the past decade, a system of information generation has grown up in parallel with the traditional expert-driven system. In the old system everyone defers to an expert, while in the new system the public combines its resources. In the old system, documents are fixed after publication, whereas in the new system they are fluid. The old system was driven by the author's ego and increasingly by the demand for generating money, whereas the new system has revenue possibilities but has a strong sense of responsibility for the welfare of communities.

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

(All my postings from this sprint are listed in a bundle.)

FLOSS Manuals books published after three-day sprint

The final day of the FLOSS Manuals documentation sprint at Google began with a bit of a reprieve from Sprintmeister Adam Hyde's dictum that we should do no new writing. He allowed us to continue work till noon, time that the KDE team spent partly in heated arguments over whether we had provided enough coverage of key topics (the KDE project architecture, instructions for filing bug reports, etc.), partly in scrutinizing dubious material the book had inherited from the official documentation, and (at least a couple of us) actually writing material for chapters that readers may or may not find useful, such as a glossary.

I worried yesterday that the excitement of writing a complete book would be succeeded by the boring work of checking flow and consistency. Some drudgery was involved, but the final reading allowed groups to revisit their ways of presenting concepts and bringing in the reader.

Having done everything I thought I could do for the KDE team, I switched to OpenStreetMap, who produced a short, nicely paced, well-illustrated user guide. I think it's really cool that Google, which invests heavily in its own mapping service, helps OpenStreetMap as well. (They are often represented in Google Summer of Code.)

After dinner we started publishing our books. The new publication process at FLOSS Manuals loads the books not only to the FLOSS Manuals main page but to Lulu for purchase.

Publishing books at doc sprint
Publishing books at doc sprint

Joining the pilgrimage that all institutions are making toward wider data use, FLOSS Manuals is exposing more and more of the writing process. As described by founder Adam Hyde in a blog posting today, Visualising your book, recently added tools that help participants and friends follow the progress of the book (you can view a list of chapters edited on an RSS feed, for instance) and get a sense of what was done. For instance, a timeline with circles representing chapter edits shows you which chapters had the most edits and when activity took place. (Pierre Commenge created the visualization for FLOSS Manuals.)

Participants at doc sprint
Participants at doc sprint

(All my postings from this sprint are listed in a href=""> bundle.)

October 20 2011

Day two of FLOSS Manuals book sprint at Google Summer of Code summit

We started the second day of the FLOSS Manuals sprint with a circle encounter where each person shared some impressions of the first day. Several reported that they had worked on wikis and other online documentation before, but discovered that doing a book was quite different (I could have told them that, of course). They knew that a book had to be more organized, and offer more background than typical online documentation. More fundamentally, they felt more responsibility toward a wider range of readers, knowing that the book would be held up as an authority on the software they worked on and cared so much about.

We noted how gratifying it was to get questions answered instantly and be able to go through several rounds of editing in just a couple minutes. I admitted that I had been infected with the enthusiasm of the KDE developers I was working with, but had to maintain a bit of critical distance, an ability to say, "Hey, you're telling me this piece of software is wonderful, but I find its use gnarly and convoluted."

As I explained in Monday's posting, all the writing had to fit pretty much into two days. Each of the four teams started yesterday by creating an outline, and I'm sure my team was not the only one to revise it constantly throughout the day.

Circle at beginning of the day
Circle at beginning of the day

Today, the KDE team took a final look at the outline and discussed everything we'd like to add to it. We pretty much finalized it early int the day and just filled in the blanks for the next eleven hours. I continued to raise flags about what I felt were insufficiently detailed explanations, and got impatient enough to write a few passages of my own in the evening.

Celebrating our approach to the end of the KDE writing effort
Celebrating our approach to the end of the KDE writing effort

The KDE book is fairly standard developer documentation, albeit a beginner's guide with lots of practical advice about working in the KDE environment with the community. As a relatively conventional book, it was probably a little easier to write (but also probably less fun) than the more high-level approaches taken by some other teams that were trying to demonstrate to potential customers that their projects were worth adopting. Story-telling will be hard to detect in the KDE book.

And we finished! Now I'm afraid we'll find tomorrow boring, because we won't be allowed (and probably won't need) to add substantial new material. Instead, we'll be doing things like checking everything for consistency, removing references to missing passages, adding terms to the glossary, and other unrewarding slogs through a document that is far too familiar to us already. The only difference between the other team members and me is that I may be assigned to do this work on some other project.

(All my postings from this sprint are listed in a bundle.)

October 19 2011

Day one of FLOSS Manuals book sprint at Google Summer of Code summit

Four teams at Google launched into endeavors that will lead, less than 72 hours from now, to complete books on four open source projects (KDE, OpenStreetMap, OpenMRS, and Sahana Eden). Most participants were recruited on the basis of a dream and a promise, so going through the first third of our sprint was eye-opening for nearly everybody. Although I had participated in one sprint before on-site and two sprints remotely, I found that the modus operandi has changed so much during the past year of experimentation that I too had a lot to learn.

Our doc sprint coordinator, Adam Hyde, told each team to spend an hour making an outline. The team to which I was assigned, KDE, took nearly two, and part way through Adam came in to tell us to stop because we had enough topics for three days of work. We then dug in to filling in the outline through a mix of fresh writing and cutting and pasting material from the official KDE docs. The latter required a complete overhaul, and naturally proved often to be more than a year out of date.

KDE team at doc sprint
KDE team at doc sprint

The KDE team's focus on developer documentation spared them the open-ended discussions over scope that the other teams had to undergo. But at key points during the writing, we still were forced to examine passages that appeared too hurried and unsubstantiated, evidence of gaps in information. At each point we had to determine what the hidden topics were, and then whether to remove all references to them (as we did, for instance, on the topic of getting permission to commit code fixes) or to expand them into new chapters of their own (as we did for internationalization). The latter choice created a dilemma of its own, because none of the team members present had experience with internationalization, so we reached out and tried to contact remote KDE experts who could write the chapter.

The biggest kudos today go to Sahana Eden, I think. I reported yesterday that the team expressed deep difference of opinion about the audience they should address and how they should organize their sprint. Today they made some choices and got a huge amount of documentation down on the screen. Much of it was clearly provisional (they were boo'ed for including so many bulleted lists) but it was evidence of their thinking and a framework for further development.

Sahana team at doc sprint
Sahana team at doc sprint

My own team had a lot of people with serious jet lag, and we had some trouble going from 9:00 in the morning to 9:30 at night. But we created (or untangled, as the case may be) some 60 pages of text. We reorganized the book at least once per hour, a process that the FLOSS Manuals interface makes as easy as drag and drop. A good heuristic was to choose a section title for each group of chapters. If we couldn't find a good title, we had to break up the group.

The end of the day brought us to the half-way mark for writing. We ares told we need to complete everything at the end of the evening tomorrow and spend the final day rearranging and cleaning up text. More than a race against time, this is proving to be a race against complexity.

Topics for discussion at doc sprint
Topics for discussion at doc sprint

October 18 2011

FLOSS Manuals sprint starts at Google Summer of Code summit

Five days of intense book production kicked off today at the FLOSS Manuals sprint, hosted by Google. Four free software projects have each sent three to five volunteers to write books about the projects this week. Along the way we'll all learn about the group writing process and the particular use of book sprints to make documentation for free software.

I came here to provide whatever editorial help I can and to see the similarities and differences between conventional publishing and the intense community effort represented by book sprints. I plan to spend time with each of the four projects, participating in their discussions and trying to learn what works best by comparing what they bring in the way of expertise and ideas to their projects. All the work will be done out in the open on the FLOSS Manuals site for the summit, so you are welcome also to log in and watch the progress of the books or even contribute.

A book in a week sounds like a pretty cool achievement, whether for a free software projects or a publisher. In fact, the first day (today) and last day of the sprint are unconferences, so there are only three days for actual writing. The first hour tomorrow will be devoted to choosing a high-level outline for each project, and then they will be off and running.

And there are many cautions about trying to apply this model to conventional publishing. First, the books are never really finished at the end of the sprint, even though they go up for viewing and for sale immediately. I've seen that they have many rough spots, such as redundant sections written by different people on the same topic, and mistakes in cross-references or references to non-existent material. Naturally, they also need a copy-edit. This doesn't detract from the value of the material produced. It just means they need some straightening out to be considered professional quality.

Books that come from sprints are also quite short. I think a typical length is 125 pages, growing over time as follow-up sprints are held. The length also depends of course on the number of people working on the sprint. We have the minimum for a good sprint here at Google, because the three to five team members will be joined by one or two people like me who are unaffiliated.

Finally, the content of a sprint book is decided on an ad hoc basis. FLOSS Manuals founder Adam Hyde explained today that his view of outlining and planning has evolved considerably. He quite rationally assumed at first that very book should have a detailed outline before the sprint started. Then he found that one could not impose an outline on sprinters, but had to let them choose subjects they wanted to cover. Each sprinter brings certain passions, and in such an intense environment one can only go with the flow and let each person write what interests him or her. Somehow, the books pull together into a coherent product, but one cannot guarantee they'll have exactly what the market is asking for. I, in fact, was involved in the planning of a FLOSS Manuals sprint for the CiviCRM manual (the first edition of a book that is now in its third) and witnessed the sprinters toss out an outline that I had spent weeks producing with community leaders.

So a sprint is different in every way from a traditional published manual, and I imagine this will be true for community documentation in general.

The discussions today uncovered the desires and concerns of the sprinters, and offered some formal presentations to prepare us, we hope, for the unique experience of doing a book sprint. The concerns expressed by sprinters were pretty easy to anticipate. How does one motivate community members to write? How can a project maintain a book in a timely manner after it is produced? What is the role of graphics and multimedia? How does one produce multiple translations?

Janet Swisher, a documentation expert from Austin who is on the board of FLOSS Manuals, gave a presentation asking project leaders to think about basic questions such as why a user would use their software and what typical uses are. Her goal was to bring home the traditional lessons of good writing: empathy for a well-defined audience. "If I had a nickel for every web site I've visited put up by an open source project that doesn't state what the software is for..." she said. That's just a single egregious instance of the general lack of understanding of the audience that free software authors suffer from.

Later, Michael McAndrew of the CiviCRM project took us several steps further along the path, asking what the project leaders would enjoy documenting and "what would be insane to leave out." I sat with the group from Sahana to watch as they grappled with the pressures these questions created. This is sure one passionate group of volunteers, caring deeply about what they do. Splits appeared concerning how much time to devote to high-level concepts versus practical details, which audiences to serve, and what to emphasize in the outline. I have no doubt, however, listening to them listen to each other, that they'll have their plan after the first hour tomorrow and will be off and running.

July 01 2011

Matti Suuronen’s Futuro at Museum Boijmans Van Beuningen

In 2007, Museum Boijmans Van Beuningen in Rotterdam / Netherlands came into possession of the prototype of a quite spectacular piece of architecture: Finnish architect Matti Suuronen’s Futuro: house of the future.

With its distinctive flying saucer like shape Suuronen’s Futuro is an icon of 1960s design. In 1965 Matti Suuronen was commissioined to design a mobile holiday home that could be erected in poorly accessible skiing areas. The Futuro is made from polyester, measures about 3 x 8 meters, and was conceived for serial production. In part due to the oil crisis of 1973 the production was halted prematurely, but there are still a dozens of Futuros spread across the world.

The Futuro is now on display for the first time after its restoration at Museum Boijmans Van Beuningen as centerpiece of the exhibition Futuro – Constructing Utopia, which also presents twenty prints and approximately a hundred design objects from the museum’s collection.

On the occasion of the opening of the exhibition Futuro – Constructing Utopia at Museum Boijmans Van Beuningen VernissageTV met up with Jonieke van Es. She is Head of Collections & Research at the museum and tells us more about the history and concept of the Futuro, how the prototype came into possession of Museum Boijmans Van Beuningen and how it was restored, the Futuro’s relevance as a design icon, and its future use at the museum.

PS: Another Futuro is being restored currently at the University of Canberra.

> Right-click (Mac: ctrl-click) this link to download Quicktime video file.

January 24 2011

Afterimages of Life. Władysław Strzemiński and Rights for Art / ms2, Łódź, Poland

Jarosław Lubiak, curator of the exhhibition “Afterimages of life. Władysław Strzemiński and rights for art” at ms2, Łódź, Poland, explains the work of Władysław Strzemiński (1893-1952), one of the most important polish avant-garde artist. Strzemiński was a painter, designer, theoritican and teacher. The theory of Unism, which he created, was an importand contribution to the history of art of 20th century.

Strzemiński wrote many articles and books. His most important publications include: Unism in Painting (1928); Space Composition. Time – Space Rythm and its Calculations (1931) ; Theory of Vision (1958), written together with his wife, Katarzyna Kobro.

The curators invited German artist, Katja Strunz, to create the exhibition space. Thanks to her intervention in the shape of the architecture of the exhibition, we are given a new commentary to the works of Strzemiński.

Afterimages of Life is the first monographic exhibition of the artist in the period of the last 17 years. Its objective is the re-interpretation of Władysław Strzemiński’s works and placing them in the context of contemporary world.

Afterimages of life. Władysław Strzemiński and rights for art / ms2 Muzeum Sztuki in Lodz, Poland. Interview and video by Ania Ejsmont.

> Right-click (Mac: ctrl-click) this link to download Quicktime video file.

Tags: Powidoki życia. Władysław Strzemiński i prawa dla sztuki Unizm w malarstwie Teoria widzenia Kompozycja przestrzeni i obliczenia rytmu czasoprzestrzennego Muzeum Sztuki w Łodzi Łódz

July 28 2010 Links zu den Ereignissen auf der Loveparade in Duisburg und verlinkte Blogs aus dem Netz

- Dokumentationsseite - Panorama

- Mediathek


Alvar Freude - Rekonstruktions der Ereignisse am und im Tunnel mittels Video-Clips, die von diversen Teilnehmern ins Netz gestellt wurden.


2 Erlebnisberichte:

- Ich verstehe es nicht! - Julias Loveparade Blog

- Loveparade 2010 – Mein Gedächtnisprotokoll « Twitgeridoo!


June 15 2010

Four short links: 15 June 2010

  1. On Bookmarking: Dogears and Marginalia -- asking the question "how do you bookmark in real life?". I'm interested because I have recently begun obsessively collecting the good quotes and references from books I read, thanks to Amazon Kindle app's highlights. (via titine on Delicious)
  2. Systems for Open Electronic Lab Notebooks -- question from a very respected scientist (Jonathan Eisen, king of the phylogenetic tree and "phylogenomics" on Twitter) about tools and software for open lab notebooks. Turns out it's by no means a solved problem, so a good hacker working with such a lab could do some good things for science.
  3. Starbucks, Wifi, Paid Content (ReadWriteWeb) -- Starbucks announced free wifi, from which customers can access content they'd otherwise have to pay for (e.g., WSJ). Interesting to me for several reasons: libraries also offer access to information you'd otherwise not have access to; and Starbucks are turning the physical store into a virtual one as well.
  4. Writing Great Documentation (Jacob Kaplan-Moss) -- it's all true, read it and write.

June 02 2010

"YouTube Is UsTube": Creators Step in to Defend YouTube | Electronic Frontier Foundation | Commentary by Corynne McSherry | EFF 20100531

Plenty of folks, from copyright lawyers to Internet entrepreneurs to investment bankers, have been watching the long-running legal battle between Viacom and Google/YouTube carefully, well aware that a decision in the case could have a profound effect on the future of the Internet. But most YouTube users probably haven't given it the same attention. They should, and in an amicus brief filed in support of YouTube last week, a group of YouTube video creators explains why. Calling themselves "The Sideshow Coalition" (because Viacom has called their interests a "sideshow"), these creators tell their own personal stories of how YouTube has helped them find a broader audience than they had ever imagined they could reach, with all kinds of unexpected effects. A few examples from the brief:

* Barnett Zitron, who created "Why Tuesday," a political video blog focused increasing voter turnout that has helped register over half a million college students to vote.

* Mehdi Saharkhiz, who created a YouTube channel to spread awareness about government human rights abuses in Iran and frequently posts videos from contacts in Iran who record the videos on their cell phones.

* Phillip de Vellis, who created and uploaded to YouTube a video supporting President Obama’s candidacy, hoping it would be viewed by a few thousand people. "Instead, millions viewed it and the San Francisco Chronicle described it as 'a watershed moment in 21st century media and political advertising.'"

* Arin Crumley, who could not get conventional financing for a film he wanted to make, and decided instead to self-produce it and post it to YouTube. The first full length movie ever uploaded to the site, it was viewed more than a million times, and then the Independent Film Channel picked it up.

* Dane Boedigheimer, who wanted to be a filmmaker since he was 12 years old and would spend hours each day with his parents’ 8mm camera. "In the conventional media, it would have taken years before he might even have a chance to direct films. However, with YouTube, Boedigheimer was able to create a series called 'Really Annoying Orange' whose episodes have been viewed 130 million times."

These creators praise YouTube for removing the gatekeeper between them and their audiences. “We can now be our own television and cable stations and our own record labels and record stores. We suspect that the threat that truly concerns Plaintiffs is not copyright infringement but just competition.” Unlike most of the parties and amici who have filed in this case (including EFF), these friends of the court don't focus on the legal doctrines at stake in this case. Instead, they remind us why these legal issues matter, i.e., what's really at stake in a case that tries to hold intermediaries liable for what users post online:

"It is pretty clear that on a scale of incentives to censor, the billion dollars that Plaintiffs seek in this lawsuit rates pretty high. If YouTube is made responsible for everything that we say, then naturally YouTube will want to exercise control over what we say. No online service would risk enabling the universe of users to speak in their own words if it faced liability for anything that anyone said. Therefore, we ask that as the Court decides this case, it consider not just the interests of those who appear in the caption, but also our interests as creative professionals and the interests of the hundreds of millions of people who have viewed our work. We are not a sideshow. We are what YouTube is all about and what this lawsuit should be about."

Just so.

AttachmentSize Sideshow-Coalition-amicus.pdf210.06 KB

March 24 2010

Interview with Designer Yves Béhar / Part 2/2: One Laptop Per Child and other projects

Industrial designer Yves Béhar is know for his engagement in the One Laptop Per Child (OLPC) project. For OLPC he designed the XO laptop. In the second part of the interview with Yves Béhar at Baselworld 2010, he gives us an update on the OLPC project and talks about his work, the future of design and the role design can play in making the world a better place, and the projects he is working on at the moment.

Born in Switzerland in 1967. Graduated from Art Center College of Design. Established his design studio, fuseproject in 1999. He brings a humanistic approach to his work with the goal of creating projects that are deeply in-tune with the needs of a sustainable future. He also combines technological innovation with design. His major work includes the XO laptop for OLPC (One Laptop Per Child), LEAF LED light for Herman Miller, and “Jawbone” Bluetooth headset for Aliph. His innovative designs have garnered more than 150 awards, and his work is in the permanent collections of museums including the Centre Pompidou, MoMA, the Die Neue Sammlung – The International Design Museum Munich and The Art Institute of Chicago.

> Right-click (Mac: ctrl-click) this link to download Quicktime video file.
> Click this link to watch Quicktime video in new movie window.

Related Articles:


March 23 2010

Interview with Designer Yves Béhar / Part 1/2: Issey Miyake Watch Series VUE

On the occasion of the presentation of Seiko’s Issey Miyake watch series VUE at Baselworld 2010 in Basel, Switzerland, VernissageTV met with the designer of the watch, Yves Béhar.

In the first part of the interview, Yves Béhar talks about the new Issey Miyake watch series called VUE: the basic idea, the materials, and shows us the watch and an animation that visualizes the concept behind VUE.
In the second part of the interview, Yves Béhar talks about his work and his studios in New York and San Francisco, his involvement in the One Laptop Per Child (OLPC) project for which he designed the XO laptop, the future of design and the role design can play in making the world a better place, and the projects he is working on at the moment.

The complete interview is also available on our HD page.

Since 2001, under the direction of ISSEY MIYAKE, Seiko Instruments Inc. has collaborated with designers such as Shunji Yamanaka, Harri Koskinen, Tokujin Yoshioka, Naoto Fukasawa and Ross Lovegrove. This time, Yves Béhar was commissioned to design a new watch series.

Designer Statement by Yves Béhar: “A watch is a Mindset about the idea of time. When considering reading the time of day, my main question is: why do I need to see all twelve numbers when only one is needed? The watch’s unique approach is to present one number appearing only, while the previous hour slowly fades out of view, and the next one fades into view. This magical appearance reminds me of the time just passed, and the future incoming…it says, ‘time is precious, yet always presents us with a surprise ahead. The mindset of the watch is to let the mystery of time be experienced: the watch is a way to feel time’s appearance and disappearance in our lives. By seeing only the current hour, while the last hour representing the past and the next one representing the future subtly fade in and out, we can live a new view of time.”

> Right-click (Mac: ctrl-click) this link to download Quicktime video file.
> Click this link to watch Quicktime video in new movie window.


Older posts are this way If this message doesn't go away, click anywhere on the page to continue loading posts.
Could not load more posts
Maybe Soup is currently being updated? I'll try again automatically in a few seconds...
Just a second, loading more posts...
You've reached the end.
No Soup for you

Don't be the product, buy the product!

YES, I want to SOUP ●UP for ...