How to use this Page

When I noted that I had been busy with conference planning, one angle to that I had left out is my crash education in DocBook XML, a markup language used for technical documentation.

I’ve spent close to a year circling around the question of documentation for an open source software project. Documentation is one of those maturational issues for open source software (and before we get too far, I will add that there’s no shortage of lame documentation in the proprietary software world — but that’s not the problem I’m trying to solve).

I know what doesn’t work, such as assuming documentation will naturally bubble up from the gift economy (the kind of woo-woo philosophizing up there with assuming an unregulated market will police itself). That approach yields at best a smattering of notes in a hodgepodge of formats. You also can’t just point contractors toward the project and say “write this.” I mean, you can, but it won’t work.

In the end, you need focus and direction — or as I put it in a talk a couple weeks back, some people, a plan, and a pickaxe.

The kewl thing about Evergreen is that the project is now approaching the critical mass required to support almost anything the community wants to do, including establishing a documentation project. (I don’t kid myself that a community documentation project could necessarily handle all documentation needs for an open source community, but without a project, we’ll never know what those needs are to begin with — and a community can bite off some chunks of the problem.)

Evergreen’s now got the people, and they are ready and willing to plan. But to give this project direction, it also needed the pickaxe, which is where DocBook XML comes in.

When you look at all the options for formatting documentation, and then look at the basic documentation needs of any project, you work your way to DocBook XML by process of elimination.  Assuming your project needs a single-source, standards-based, non-binary documentation format that supports translation, reuse, and other requirements, with an active user community, and strong fee-or-free toolsets, you end up with DocBook XML or DITA. The ramp-up for DocBook XML is much less daunting than DITA (though not without plenty of daunt on its own), in part due to a couple of excellent books (and though they are freely available online, it’s much easier to buy the print books and have them parked near your keyboard for ready reference).

DocBook XML is a lot like democracy (to paraphrase some pundit): it doesn’t look so great until you compare the alternatives. Nobody thinks writing XML is a walk in the park, and after you’ve produced lengthy XML documents, you still have to transform them into HTML (or PDF), and even at that you need to style the pages so they’re all purty, because plain HTML looks so 1993. But again, after close to a year of banging my head on the wall, I get it. DocBook. All righty.

But it’s one thing to suggest using DocBook XML — and building an entire project around it — and another to actually demonstrate it in action. So about six weeks ago I realized that if I was going to make a convincing, project-energizing argument for DocBook XML — an argument first made two years ago by others in the community and repeated several times  hence, with no objection but also no action — I was going to have to get serious about learning DocBook XML, if not to the level of expertise, at least to a minimal competence.

(It helped that I had been reviewing an intern’s beginning DocBook projects for a couple of months; as is often the case with teaching, I quietly absorbed more than I realized during the process of evaluating the student’s work.)

So in addition to working on the conference planning stuff, I got up at the butt-crack of dawn for weeks on end to review, validate, revise, tweak, experiment with, and otherwise produce real DocBook XML examples. After experiencing the pain of working at a DOS prompt with some free tools, I moved to a nice editor, oXygen, and that helped somewhat — but there was still much to learn (and I repeated all my examples with the free tools just to be sure they could be produced that way as well).

And then, of course, there’s the beer connection

When I started writing this blog post I saw a clear link between this and homebrewing. Circling back to that idea, I still see the similarities.

In both cases I have been learning a fairly arcane skill through books, websites, discussion groups, and iterative practice. There’s a geek level to both I enjoy; I’m not ever going to be a truly yee-haw XML/XSL cowgirl any more than I am going to open my own brewery, but I admit that the first time I got a reasonably long document to not only transform but to get styled with CSS, I did feel a wee spark of pride — similar to the first beer batch I made where I actually, and successfully, “mashed” (that is, converted malted barley into wort, the liquid that when boiled with hops and activated with yeast, eventually becomes beer).

Plus in both cases, by mastering some fundamental skills (and a domain vocabulary), I can now communicate within their respective communities. I understand terms such as single-source, transform, validate, XSL, stylesheet, FO, FOP; sparge, pitch, vorlauf, lauter, rack, mash, tun. (And to my delight, there is an XML schema for beer called, of course, BeerXML, proving that all roads lead to London.)

The ability to communicate is key; getting past that initial hurdle is crucial for learning. (Remember Helen Keller, spelling out “water”?) I may not understand every question that flies past me, but my feet have some purchase in the loam of their fields.

I don’t know. Maybe I’m just in it for the language. But these processes happening in parallel have me marveling at our capacity to keep learning, sometimes when we least expect to.

Bookmark to:

This afternoon I drive to Norcross, kicking off over a month of travel here and there (with many mini-trips built in).

10/12 - 10/16: TLH to Norcross. Working on-site at My Place Of Work. Mini-trips include Newton County Library System, Athens Public Library, and COMO. I wanted to touch base with a colleague who said sorry, she’s a bit busy with the 2nd annual Atlanta Queer Literary Festival.

WHAT!! I said. But of course I must put that on my homosexual agenda! So in between doing research for various trips and reading excellent drafts of software documentation by the illustrious Evergreen Docs Crew, I am gulping down Heaven’s Coast in preparation for hearing Mark Doty — and waving at busy Cal Gough from afar! I’m trying to see if I have courage to approach the open mike or will just sit there feeling like a wimp (and no, I’m not the Karen G. hosting that mike!).

10/16-10/17. Return to TLH. I’m largely pre-packed for Cincinnatti (just need to grind fresh Peet’s), which fortuitiously requires a very different set of clothes than what I’m wearing in ATL.

10/17 - 10/19: LITA National Forum. I was really going to learn (I find Forum is a great learning conference) but last week my colleague and fellow UIUC alum Aaron Trehub asked me to emcee a panel on distributed networks for digital preservation. I’m thrilled, because this is a topic that I feel very strongly about but don’t work directly in these days. I hope Tim Spalding’s talk is taped because the way the flights went I am going to walk in halfway through it at best.

10/19 - 10/22. Shelter in place in TLH. Vote on 10/20 (first day of early voting).

10/22 - 10/25. Statewide directors’ meeting in Baton Rouge; talking about open source and what it means to be a community librarian (good for me to have it figured out by then!). I get to Louisiana with enough time to make some liberry visits — I’m flying into NOLA specifically for that reason. I stay over in NOLA Friday night because Sandy has a conference there. Handy! We fly back to TLH together.

10/25 - 10/26. Wash, pay bills, and pack.

10/26 - 10/29. Norcross, with some internal round-trips.

10/29 - 11/1. TLH. Hunker in and work.

11/1 - 11/16. (or 11/15, unclear just yet). VALA/CAVAL 30th anniversary; five speaking stops. My itinerary in Australia takes me around what looks to me like the southern belt of the country. I believe I will actually get to meet Kathryn Greenhill and Fiona Bradley face-to-face! I’ve heard from some other folks I know. My co-presenter and I will be sightseeing a bit together too. I’m reading several fat travel books and a little Bill Bryson — if you have one you think is good to travel with, give a holler soon.

In prep for VALA/CAVAL, I’m also reading a slew of books I haven’t quite figured out how to track. Some are in PINEs, some are in WorldCat, some are local… I may try Zotero. I’d like something that would let me present an annotated bibliography online, in the order I choose.

My keynote at Access 2008 was a kind of early version of that talk, btw, sans the research I hope to bring to this. The working title (also used at Access) is “open++.”

Bookmark to:

Whew, week of shiny-new-job! I’ve posted my first post at the company blog. Expect many more — I’ll try to mention the best ones here, but you may want to subscribe.

ALA is imminent! I’ll be at the Equinox booth, 1888 — at least half the time, anyway — and I’ll be part of the crew doing presentations, one-on-one booth meetings, and general meet-and-greet.

I’ll also be presenting (or at least dog-paddling) at LITA’s Top Tech Trends, LITA’s Ultimate Debate, and Monday morning’s LITA Next Gen Catalog Interest Group. Plus I’ll be at meetings for Jim Rettig’s implementation task force, the Electronic Meeting Participation Task Force, LITA Forum 2009, and the OCLC Blog Salon.

So yesterday I started my new job as Community Librarian at Equinox. According to Library Journal, I’m “opinionated,” which I will generously interpret as praise (even though LJ’s archives suggest this is a word that for their reporters cuts both ways).

I’m still finding the bathroom around here, but I definitely feel “opinionated” about open source in libraries: it makes sense, and that’s why I’m getting involved in it. I plan to share my opinionations on blogs (Equinox and the Evergreen community both have blogs), magazine articles, presentations, one-on-one discussions, and whatever other venues allow me to opine.

(To clarify my whereabouts, I’m going to be teleworking for Equinox, with an occasional on-site sync-up, and for now we’ll stay in Tallahassee. This week I return to Tallahassee Wednesday early evening so I can fly out the next day.)

Bookmark to:

The truck farmers have arrived in Tallahassee — or, we could call them, purveyors of open-source agriculture.  This gentleman is at Lafayette and Magnolia most Fridays and Saturdays, and his sugar-sweet, flavorful melons made some scrumptidiliumptious sorbet this weekend.

But I have been absorbed in my own “fruitful” exercises…

ALA Techsource is once again actively publishing, with several new writers and a new editor at the helm, and Jason Griffey interviewed me about my new job at Equinox, open source, kittens, etc. Happy to see Techsource’s star in ascendance once again!

It has also been a week of taxes (I often file extensions, which means my accountant and I are both a little saner when it’s “my” tax time, but that bird eventually comes home to roost), writing my last super-secret internal MPOW report (this one on Shibboleth, which I keep accidentally calling “Chimera” — was it Jung who said there are no mistakes?), and getting ready for essentially three weeks on the road, with quick scoots back to home base: New Mexico, Cape Cod, Atlanta, and Anaheim, from June 7 to July 1.

Georgia Public Library Service has an interesting position open. If you’re savvy but not a developer, don’t let the word “software” stop you; note the emphasis on project management, Evergreen, lee-ayzing, etc. Looks like a great job for someone with excellent project/people skills and a passion for quality library software!

I heard tale of the latest draft of ILS-Discovery recommendations from the Digital Library Federation by way of John Mark Ockerbloom (whose wonderfully syncopated name surely deserves a nursery rhyme: “John Mark Ockerbloom/Saw an ILS;/John Mark Ockerbloom/Said, “What IS this mess?”).

Dopplr now calculates carbon footprints for your trips. I stopped using Dopplr because it was too much fuss for the value — one more place to record stuff, not enough “network effect” to really make it social — but the personal carbon footprint calculation alone might be worth it to me. Might. Possibly. We’ll see.

I often find myself in situations where I want to record a good thought or send a reminder, and cannot write… in a car, a line at the airport, etc. Per Liz Lawley (”Mamamusings”), I finally tried Jott. As Liz says, “when you call their number it listens to your message and transcribes it for you,” then off it goes to your email or calendar or what-have-you. It’s utterly satisfying magic — I’m hooked! Give Jott a try.

Speaking of situations, I have elected to reduce the opportunities for those, and have ordered a GPS. (It was $359 the day I bought it — today it’s $413! I bet Amazon was going toe-to-toe with CostCo, which had it for $349.)

I have rented a GPS a couple of times on business trips where I had to drive in unknown areas, and it was love, love, love. A GPS changes the trip, which is its own reflective post for the future. I rationalized the purchase because some needed car repair came in well under what I thought it would be. (You see why I am not an accountant — though a high-end GPS in a fifteen-year-old Honda has its own logic. The car has outlasted at least five computers, come to think of it, and is still spry, fuel-efficient, and a comfortable ride. Go you, my little red friend.)

While looking at my accounting for last year and observing some minor billing for my web-based fax service (a great way to eliminate the hassle of incoming faxes), I reflected that I have received no faxes in the last year and sent only three (and at that, under duress — I usually persuade people that snail-mail will work fine). I coped with great slurries of faxes in California (despite my pleas and arguments to the contrary) but expect those agencies have Moved On by now.

I expect to post a little en route, and more once my “writing retreat” ends and I am romping with my baby sister in Santa Fe. We’ll see!

On to the last day of work…

Bookmark to:

By Kirsty OUP-UK

“Nae man can tether time or tide,” said Robert Burns in Tam o’Shanter. Over the 200 years since the Scottish Bard’s death in July 1796 his poetry has been celebrated the world over through a network of Burns Clubs. Since tomorrow is Burns Night, I though today would be the ideal time to post this entry from The Oxford Companion to Scottish History, which tells us all about Burns Clubs and how they came into being.

Burns clubs are societies devoted to the life and work of Robert Burns. The earliest meeting of devotees of Burns took place in the summer of 1801, only five years after the poet’s death. Nine gentlemen of Ayr, friends and admirers of Burns, held a dinner in the poet’s birthplace (then a tavern). Haggis formed a part of the fare and Burns’s Address to a Haggis was recited. The Revd Hamilton Paul delivered the toast to the ‘Immortal Memory’ of Burns in verses of his own composition. Thus was established the essential form of the Burns supper. Before breaking up, the company resolved to celebrate the birthday of Burns the following January. Out of these informal gatherings the Alloway Club developed, later dinners being held at the King’s Arms, Ayr, in midsummer. This early club ceased to exist in 1819 and was not revived until 1908.

The Greenock Burns Club owed its genesis to a much older body called the Greenock Ayrshire Society, which appears to have held Burns suppers from 1802 and by 1811 had metamorphosed into the Greenock Burns Club. Greenock have had a continuous existence down to the present day, whereas the rival Paisley Burns Club (1805) was in abeyance from 1836 till 1874.

The Kilmarnock Burns Club first met at the Angel Inn (formerly Begbie’s Tavern) in January 1808, but was dormant from 1814 to 1841. The Dunfermline United Burns Club (1812) likewise had a lengthy period of suspended animation, being revived in 1870. Though a relative latecomer, the Dumfries Burns Club (1820) has flourished ever since its foundation. It arose out of the campaign (1813–19) to erect a mausoleum over the poet’s grave.

By 1810 Burns suppers were being held on an ad hoc basis in many parts of the country. The first in England was held at Oxford in 1806 and Burns Night celebrations were taking place in London by 1810. The idea spread to India in 1812, and thereafter to Canada, the USA and the Australian colonies. The Burns movement received enormous stimulus from the celebrations of the centenary of the poet’s birth in January 1859; out of the many hundreds of dinners and concerts around the world developed some of the oldest clubs in existence today. Nothing was done to bring them together until February 1885, when Burnsians met in London for the unveiling of the monument in the Thames Embankment Gardens. A meeting in Kilmarnock on 17 July formally instituted the Burns Federation, with its international headquarters in the town where the poet’s works first saw the light of day in printed form.

In its inaugural year the Federation had ten members: eight clubs in Scotland and two in England. A further 23 joined in 1886, including ten in Scotland, six in England, one in Ireland, two each in Australia and the USA, and one each in Canada and New Zealand. Progress was slow in the early years, but the launch of the Burns Chronicle in September 1891 gave the Federation fresh impetus and in the run-up to the centenary of the poet’s death in 1896 it grew dramatically.

By 1925 the number of affiliated clubs had grown to 350, at which level it has remained remarkably constant ever since, although many of the older clubs have disappeared and new ones continually take their place. Annual conferences were confined to Kilmarnock until 1894 when Glasgow was the venue. In 1907 it went south of the Border for the first time, to Sunderland. By the 1930s, the custom of holding the conference alternately in Scotland and England was well established. Since 1978, when London, Ontario, was the venue, the conference has taken place in Canada or the USA on several occasions. The current number of members affiliated to active clubs worldwide is estimated at 80,000.

Share This