05 Mar 12: Open and Agile. For tech writers.


I had the good fortune last week to speak at and participate in "Management Day" put on by the Toronto Community of the STC. The purpose of this all-day event was to introduce technical communicators (not necessarily managers) to Agile development through hands-on experience with an open-source project. The workshop on Agile was conducted by Agile consultant Gil Broza, and the open source project that benefited from the participants' work was Ushahidi, which provides software for collecting, visualizing, and mapping issue- or event-related information. My role in the event was to introduce the participants to community-generated content, both from the contributor side and the community-management side.

The day started with presentations by me on community-generated content, Gil on Agile, and Heather Leson on Ushahidi. Then the group broke into teams and did two one-hour iterations of work on Ushahidi's developer wiki, with debriefing sessions after each iteration, and a Q&A at the end of the day. (There were breakfast, lunch, and snacks at various times as well.) I had been skeptical that anything useful could be accomplished in such short iterations, but this was not Gil's first rodeo. He and Heather had come up with several tightly-focused user stories for the groups to choose among to work on. By the end of the day, the two teams had delivered:

So, this event was a win all around. Ushahidi got some professional improvements to their wiki, and the participants got a taste of Agile, a taste of open source documentation, and the good feelings of helping a project that helps people all over the world tell their stories. Many thanks to STC Toronto for hosting, and especially Michele Marques for organizing the event.

Though Gil Broza's slide-less presentation put mine to shame, I've still posted the slides from my presentation, Lessons in Community from Open Source Projects, on Slideshare, as I promised I would.


Category: Open Source | Posted by: jmswisher | 2 Comments

10 Aug 11: MDN doc sprint, August 12-13, online and in South Austin

One of my responsibilities at Mozilla is organizing documentation sprints to work on developer-oriented content for the MDN Documentation Center. Since last fall, we've done four doc sprints, with two that had in-person gatherings, and two that were all virtual, that is, with everyone participating "remotely".

We're doing another doc sprint this week, from Friday through Saturday, August 12 to 13. This one is virtual, in that there's no centralized gathering. But that doesn't preclude distributed local gatherings. I'll be hanging out at Fair Bean Coffee on South 1st Street in Austin on Friday and Saturday afternoons. Please come join me if you're interested in seeing what a doc sprint is like, and pitching in. Here are links to Plancast for both days:

The focus of this sprint, as usual, is open web technologies such as HTML, CSS, and JavaScript. (Though if you have expertise in Mozilla-specific topics, you're welcome to work on those, too.) Don't worry about having to write something from scratch. If you're a writer or editor, you can check topics that are tagged as "Needs Editorial Review"; if you're a web techie, you can check for "Needs Technical Review" or "Needs Code Examples".

If you're not in Austin, you can still participate on your own. If you happen to be in Bordeaux or Taipei, you can join doc sprint meet-ups in those cities. Or you can start your own meet-up.

Details about the doc sprint are on the Mozilla wiki. You'll need to register for an account on MDN, and get a way to connect to IRC to chat with other sprinters.

I hope to see you at the sprint, in the flesh or online!

Category: Open Source | Posted by: jmswisher |

06 Dec 10: Vote for Booki for the Drumbeat/transmediale Open Web Award

For nearly two years now, the FLOSS Manuals project has been working on developing a new platform to support not just its own work, but collaborative authoring and publishing of open content in general. This platform is called Booki (for "book wiki"). I've alluded to Booki occasionally on this blog, but haven't described it in detail.

Booki is designed to help people collaboratively write books online. It builds on the knowledge that the FLOSS Manuals project has gained from trying to adapt existing wiki software to support book creation and publishing, but starts fresh as purpose-built open source software. You can learn about the vision and planned features of Booki from its design document on the FLOSS Manuals site. Out of the box, it supports contributors working together to create open content, tracks attributions for licensing purposes, provides facilities for remixing content, and publishes to multiple output formats, including HTML, print-formatted PDF, and various e-book formats. The Booki blog has a great series of tutorial articles introducing Booki's features.

The development investment in Booki is starting to bear fruit. An instance of Booki has been in beta testing at booki.cc for several months now. You can test-drive Booki by creating a login on that site, and then creating or editing open content as your heart desires (which can be any kind of "comprehensive text", not just software manuals). The Booki software has reached a point of maturity and stability such that the FLOSS Manuals project is beginning the migration of its existing manuals and production website to a Booki instance.

Sounds great, huh? Want to help?

Booki has been nominated for a Drumbeat/transmediale Open Web Award. You can help support the completion of Booki by taking two very simple steps:

  1. Register for an account on the Drumbeat site. This won't subject you to any e-mails (other than sign-up confirmation) unless you opt in to the Drumbeat monthly newsletter. Drumbeat is a project of Mozilla, which is very serious about protecting your privacy.

  2. Click the Vote button on Booki's project page.

That's it! As an optional step, you can leave a comment about why you think Booki is good for the open web. Comments and other project activity will be considered by the judges in addition to the raw vote numbers. Voting is open until February 4, 2011, and the winner will be announced at the transmediale awards ceremony on February 6, 2001.

But why wait? Vote now while you're thinking about it.

Category: Open Source | Posted by: jmswisher |

04 Nov 10: Links round-up from Learning, Freedom, and the Web

I told some people that I would tweet and blog from the Drumbeat Festival for Learning, Freedom, and the Web. However, I've far too busy engaging with people at the festival in meat-space to think much about engaging virtually. Search on Twitter for #drumbeat if you want to follow those who are virtually engaged at the festival.

Here is a (far from exhaustive) list of links I've collected for projects and people I've encountered, mostly from the opening Science Fair. Draw your own connections and conclusions.

Category: Open Source | Posted by: jmswisher |

21 Oct 10: News from FLOSS Manuals

Here are a few happenings related to the FLOSS Manuals project:

[*] Speaking of voting, if you're in the US and registered to vote, please do so on November 2. Or before, if possible where you live. Early voting has started here in Texas.

(Updated 22 Oct 2010 with current book sprint info.)

Category: Open Source | Posted by: jmswisher | 1 Comment

18 Oct 10: Guerilla SEO for JavaScript documentation

While I was preoccupied with the MDN documentation sprint, an amazing movement started right under my nose.

At the European JavaScript Conference (JSConf EU) a few weeks ago, Chris Williams, the conference curator, issued a call to arms to JavaScript developers to improve the quality of their community. The first rallying point he highlighted was the need to make it easier for newcomers to learn to use JavaScript according to the best practices of the "best and brightest" of the field, that is, those who attend conferences such as JSConf. He demonstrated the poor quality of the links that currently rise to the top of Google for search terms that might be used by someone learning JavaScript, including links to Wikipedia, to a tutorial site whose JavaScript pages have not been updated in several years, and to the download page for Java, a completely distinct programming language. He challenged those assembled or watching online to write documentation on proper use of JavaScript for both newbies and advanced programmers. And he announced the PromoteJS campaign, in which web developers add a badge to their website with a link to the JavaScript documentation on Mozilla Developer Network, like this:

How To Learn JS

In essence, PromoteJS is attempting to hack the Google rankings of MDN's JavaScript pages by increasing the number of inbound links to it. This is not link spamming, because in every case, the link is relevant to the authors and readers of the site on which it appears.

Has this had an effect? It's starting to. Chris also launched Are We First Yet?, a site to track the Google rankings of key JavaScript-related search terms. So far, only "JavaScript documentation" has an MDN link as the first Google hit. But that's better than the situation before. And traffic to the MDN JavaScript pages targeted by the campaign rose by 700% in the two weeks following JSConf EU. Chris's guest post on hacks.mozilla.org should give another boost to the campaign.

Of course, inbound links are only part of the search-ranking equation. High quality content that uses the target search terms is also important. We'll be working on improving this over the next weeks and months. I hope that Chris's call to action will inspire more JavaScript experts to not merely add a badge to their sites, but to actively contribute content to MDN.

While the PromoteJS campaign has Mozilla's support (and uses the MDN robot dinosaur with permission), it is a grassroots effort started from outside Mozilla. And it is the result of open source developers realizing that educating newcomers through good documentation is essential to the sustainability of their field. I hope that developers of other open source projects and technologies will learn from this example and follow it.

My hat is off to Chris and his collaborators on PromoteJS. Wow. Just wow.

Category: Open Source | Posted by: jmswisher |

13 Jul 10: Mozilla Summit 2010 links

I spent most of last week at the Mozilla Summit in Whistler, British Columbia. I'd like to have something pithy and insightful to say about it (because I hear that my reflections on conferences make my blog "come alive"), but mostly I am overwhelmed and speechless at the combination of people and technology that I experienced. The Mozilla Summit is an invitation-only event that brings together Mozilla employees, community leaders, and selected friends of Mozilla for three days of sharing, connecting, and planning. There were inspiring keynote speeches, mind-blowing demos, informative and productive breakout sessions, five-minute lightning sessions on a huge variety of topics, a "science fair" of even more demos, a "world expo" with over 30 locales represented, and fabulous food throughout.

Rather than try to express it myself, here are a few links related to the Summit:
Whistler is a year-round resort town, but it's best known for snow sports (despite disappointing snowfall for the Winter Olympics). It was refreshing to go to the top of Whistler mountain for the final night's dinner and party, and see snow in July:
On top of Whistler mountain, July 9, 2010

Category: Open Source | Posted by: jmswisher |

03 Jul 10: My first post on Mozilla Hacks

Mozilla Hacks is Mozilla-run blog for developers that highlights innovative uses of Firefox and the open web. I've posted my first entry, Help us set priorities for docs. As I mention in the post, Mozilla is planning to start doing doc sprints to improve the developer-oriented content on the Mozilla Developer Network site. So we're soliciting input from the developer community on what their greatest documentation needs are.

It's exciting for me as a techwriter to be able to get direct feedback from members of the documentation audience, and not have to go through intermediaries such as support, consulting, or sales. I no longer have to guess about what they want, because, believe me, they are more than willing to express themselves! Votes are already pouring in to the Dev Doc Priorities forum. Users have 10 votes, which they can spread around multiple topics, or pile them all on one. As I write this, "Multithreading in JavaScript" is in the lead, but "HTML Reference" is only a few votes behind.

Category: Open Source | Posted by: jmswisher |

17 Apr 10: Texas Linux Fest and Firefox mini-sprint recap

Now that I've had a week to recuperate, I can give a recap on last weekend's Texas Linux Fest and Firefox mini-sprint. Here are my personal highlights.

FLOSS Manuals table

Anne Gentle and I staffed a vendor table for FLOSS Manuals, at which we gave away stickers and sold books that were written through FLOSS Manuals. Anne had planned to set up some FM books on Amazon CreateSpace to print and take to sell at TXLF. However, that didn't get ironed out in time, so she had copies made at a local print shop instead. More expensive per copy, but actually ready in time for the Fest. She also got a roll of 500 stickers printed, to give away. (Many thanks to Anne for getting all that stuff printed!)

Our table was at the back of the vendor space, near the ladies' room. That was convenient for us, and didn't seem to reduce the traffic to the table. We got lots of interest at the table, with a number of people saying "I had no idea such a thing existed". So we have definitely spread the word.
Janet and Anne talking to Joe Brockmeier at the FLOSS Manuals table

Presentations

Anne and I gave a presentation about FLOSS Manuals, highlighting how it can help open source projects address their documentation needs. Anne has put the slides on Slideshare.
Janet and Anne presenting about FLOSS Manuals

I gave another talk with David Cramer about how non-programmers can contribute to open source projects. We changed the title after the programs had been printed to "Collaborating with Non-programmers", which sounds less one-sided than the original title.

I didn't attend many of the other talks during the Fest, as I was staffing the table. I saw the first part of Joe 'Zonker' Brockmeier's opening keynote, "A Musical Guide to the Future of Linux", in which he compared various operating systems and Linux distributions to music bands. Unfortunately, I had to go set up for my talk with Anne, so I didn't hear the end, in which he explained how Linux itself could become less like the Ramones, and more like the Beatles.

I also saw Amber Graner's talk on her experiences as an "NTEU" (non-technical end user) of Ubuntu. Amber may be non-technical, but she is nonetheless a geek (that is, one who combines intelligence and obsession). She dove into the Ubuntu community headfirst, and a year and a bit later is a team leader of a local ("LoCo") Ubuntu group and of the Ubuntu Women Project, a blogger for Ubuntu User magazine, and an editor for Ubuntu Weekly News. She has also been to at least six Linux, Ubuntu, or open source conferences or events. She's certainly proof positive that there can be space for non-technical folks in open source. Non-obsessed folks, that's another question.

The closing keynote was by Randal Swartz. It highlighted many of the same points as David's and my talk about ways to contribute to open source other than programming. However, his talk had more personal examples and anecdotes about Larry Wall, Linus Torvalds, and Richard Stallman.

Firefox mini-sprint

I skipped the post-Fest pub crawl on 6th Street, though I did go to dinner at Chuy's, organized by Joe Cooper of Webmin. Our group gradually grew from about six to about two dozen, such that we didn't get seated until after 9pm. It was a nice chance to talk to an assortment of attendees from the Fest, including some fellow IBMers.

I was glad, then, that I hadn't scheduled the Firefox sprint to start until 11am on Sunday. The idea of doing a mini-sprint after TXLF came from Joe Brockmeier, who gave the opening keynote. He's a technology journalist and until recently was a community manager for openSUSE. I picked the Firefox update as a smallish chunk of work that could potentially be done in a day.

I announced the sprint on the FLOSS Manuals discussion list, on my blog, on the TXLF mailing list, and on the Mozilla Support Contributors Forum. Zonker mentioned it during his keynote, and I had mini-flyers at the FM table with the
details. I had no idea who would show up besides Zonker and me.

We had two additional people come to the coffeehouse to help with the sprint, and two remote contributors. I got email from one person who looked for us at the coffeehouse and didn't see us :-( and there was one person who came to hang out and sprint on a different project (I had extended that invitation in the TXLF announcements).

I didn't have much time to prepare for the sprint, since I was also preparing for my talks. So my first task during the sprint was to go through the list of new features in Firefox 3.6 and identify where that info needed to be added to the FM manual. I found about 15 tasks. By the end of the sprint on Sunday, about one third of those had been completed.

So, there is more work to do before the Firefox manual is up to date. If you're interested, please take a look at the previous post to see how to get started. Then look at the ScratchNotes page, pick something to update, and then mark it done when you're done.

I think the sprint worked out reasonably well, given that it was organized at pretty much the last minute (e.g., after out-of-towners had made their travel plans). With more advance notice, we might have gotten more people. But at least a few people got a chance to try out the FLOSS Manuals tools and process.

Category: Open Source | Posted by: jmswisher |

09 Apr 10: Impromptu Mini-sprint for Firefox, April 11th

I wrote last year about the book sprint for Firefox that I helped coordinate last year as part of DocTrain West. The book that we created in two days in March 2009 was updated by Firefox folks for Firefox 3.5 in July 2009.

At very much the last minute, I'm putting together a one-day mini-sprint to update the Firefox book to correspond to Firefox version 3.6.

It will be on Sunday, April 11th (the day after the Texas Linux Fest), from 11am to 4pm Central US time (OTC-6).

Everyone is welcome to join in, for whatever amount of time you can spare.

If you're in Austin, meet us at Genuine Joe Coffeehouse, 2001 West Anderson Lane. Let me know [janet at flossmanuals dot net] if you're going to show up, so I can arrange enough space for everyone.

If you're not in Austin, you can join us remotely on the FLOSS Manuals site and on IRC (irc.freenode.net #flossmanuals) — that IRC channel is embedded in the flossmanuals site, but you can use any client you prefer.

How to participate:

  1. Download and install Firefox, if you don't have it already.

  2. Register for a FLOSS Manuals login, if you don't have one already.

  3. Review the list of what's new in Firefox 3.6. Most can just be added to existing chapters.

  4. Go to the Write section for Firefox.

  5. Pick a chapter that you want to update and click the "edit" link.


Category: Open Source | Posted by: jmswisher | 2 Comments