Category: Just Shelley

Categories
Just Shelley

Trying to save the gooseneck lamp

More detail than ‘Out’…

I fell on the ice last week and hurt my lower back/hip area. It’s been getting progressively worse and today, when I tried to walk around the gentle, flat Tanglewood Trail at Powder Creek, I fell again. Except it was 70 F, and clear trails and I didn’t slip as much as take a step, feel something very unpleasant, yell out “Ow!”, or something to that effect but perhaps a bit stronger, and kind of folded in on myself like a budding flower changing its mind.

What’s worse is that I can’t sit at my desk for more than 20 minutes without some really interesting sensations that kind of make me want to take the gooseneck lamp by the side of the computer and bash it against the desk a 100 times or so.

Right now I’m jury rigged up in bed with pillows and what not and I can access the computer (thank you wireless!). But this only works for an hour or so before the goosenecked lamp starts to look mighty tempting again. This is really tedious.

Sporadic connectivity until body behaves in such a way that gooseneck lamp is no longer in danger.

Categories
Writing

Why writing tech is hard

AKMA has been having problems with his MT installation on Windows NT 4.0. My first reaction was to say, “Dump the trash and get a real OS, Linux”, but I realized that could be less than helpful.

Reading the discussion thread where AKMA found his solution highlights how difficult it is to write about technology. Believe it or not, it isn’t all about “First, write code. Do so without error”. There is a balancing act to the coverage, and a requirement of tone and clarity for an effective technology book.

If you make incorrect assumptions about the other person’s skill level, you frustrate them and force them into a position of having to ask and re-ask questions. Never put your audience into a position of having to ask the same question more than once.

However, if you assume too low a level, then you annoy them and they usually respond with “I know that. I wasn’t asking for___. I was just asking about____.”

Mind reading helps.

I’ve authored, co-authored, or contributed to 13 books on computer technology and have written for several online and offline magazines; it never gets easier knowing what to say and how to say it. In particular, with the “Practical RDF” book I’m just now finishing (and which I should be working on, but I’m taking a break to do laundry and a little weblogging), I had to question my interpretation of how much to cover more than once. There’s a lot of material for one book — what to put in, what to leave out. Who is my audience?

(Of course, it also helps when working with a book to have excellent editors, which I do with Prac-RDF.)

I find that the best approach to tech writing is to write to a certain level, a bit lower than the book’s assumed reading audience; and then write in a matter-of-fact voice, using a casually professional manner. Whatever I do, I avoid cute. Humor is okay (why else would I call Reification “The Big Ugly” in the book?), but never talk down to your audience, and don’t get caught up in your own cleverness — your audience will cut you at the throat.

A technical writer also never, ever makes the audience feel stupid. My job as a writer is to make you excited about the techology, interested, to answer your questions before they’re asked. My job is never to make myself seem more intelligent than I am by discussing complex topics in obscure phrases. Tech writers who write to build themselves up should be forced to eat their unsold stock.

After this book is done, I mean really done, I won’t have a professional writing assignment. For the first time since 1995, I won’t have a professional writing assignment. In the almost two years I’ve had this weblog, this is the first I’ll be able to devote all my writing and my creativity to this weblog and my web sites.

I’ll be able to finish my online C# book. I’ll be able to finish my web site makeover. I’ll be able to have some fun with my photographs, and enjoy other’s photographic endevors (which are much better than my own). More time for hiking, and driving Golden Girl around the country.

I have so many tech toys I want to create. I want to create a desktop application that incorporates WYSIWYG editing and posts to MT on my server — all using the Mozilla toolkit. There’s my PostCon system and the new Quotes. And I have dozens of other things I want to create, and new technology to explore, just for fun.

There’s so many things I want to write, and so many conversations I want to have. People to meet, too. In the flesh even. Maybe I’ll even find time for romance (which I will NOT write about).

Finally, I want to become a bigger pain in the butt then I already am with the powers that be, in weblogging and in the world. I may be broke (aren’t we all?) and I may not be writing professionally, but I still have my edge, my keyboard, my weblog, my mind, and my audience. One can do a lot of damage with all that.

Categories
Writing

Season

Loren Webster has been providing reviews of poetry by Archibald MacLeish, interspersed occasionally with lyrics from Van Morrison. These have become my calm, quiet moments in an otherwise stressful, somewhat jagged-edged day.

Not being one for poetry, or at least, I assumed I wasn’t one for poetry, I found myself surprised by how much I’ve enjoyed Loren’s introductions of the poets. My favorites have been MacLeish and David Wagoner, as neither poet seems to overflow with artistic sensibility; or indulge themselves writing poetry dripping with contrived sentimentality.

Today, I especially liked a short poem by MacLeish, which I stole from Loren’s page for duplication here:

 

The Old Men in the Leaf Smoke

The old men rake the yards for winter
Burning the autumn-fallen leaves.
They have no lives, the one or the other.
The leaves are dead, the old men live
Only a little, light as a leaf,
Left to themselves of all their loves:
Light in the head most often too.

Raking the leaves, raking the leaves,
Raking life and leaf together,
The old men smell of burning leaves,
But which is which they wonder – whether
Anyone tells the leaves and loves –
Anyone left, that is, who lives.

 

MacLeish’s The Old Men and the Leaf Smoke reminds me of another poem I’m fond of; a poem whose relevancy transcends both time and faith. I was reminded of it this week when Gary Turner’s father passed away only a few weeks after the birth of Gary’s first child, Cameron Fiona. The poem speaks for me far better than any words I can create:

 

To everything there is a season,
and a time to every purpose under the heaven:

A time to be born, and a time to die;
a time to plant, and a time to pluck up that which is planted;

A time to kill, and a time to heal;
a time to break down, and a time to build up;

A time to weep, and a time to laugh;
a time to mourn, and a time to dance;

A time to cast away stones,
and a time to gather stones together;
a time to embrace, and a time to refrain from embracing;

A time to get, and a time to lose;
a time to keep, and a time to cast away;

A time to rend, and a time to sew;
a time to keep silence, and a time to speak;

A time to love, and a time to hate;
a time of war, and a time of peace.

The Christian Bible: Ecclesiastics 3

Categories
Writing

O’Reilly twenty-five year anniversary

O’Reilly is celebrating it’s 25 year anniversary. That’s a lot of critters on a lot of covers. Congratulations to the many people I have worked with at O’Reilly, especially Simon, Tara, David, Andy, Linda, Ron, Edd, Nate, Todd, and Derrick

I’m celebrating by finishing the first draft of the last book I’m writing for O’Reilly.

Rah.

Categories
RDF Writing

Final TOC and home stretch

Next week I’m delivering to my editor the complete first draft of “Practical RDF” for O’Reilly. Yeah, finally. No one has seen the complete TOC, including the tools, APIs and whatever used in the book and I thought I would provide a heads up before the book is released for public review.

If you’re interested, the TOC is duplicated below. If you have concerns about the technology used, or are curious as to why I’m covering one tool over another, or suggestions about tools/apis/topics you feel I should have covered, please leave a comment or send me an email.

Once the book has had a look over by my editor, I’ll be posting OpenOffice versions of each chapter for chapter by chapter review at http://rdf.burningbird.net.

The book ended up featuring over 50 different tools and APIs, in seven different languages (Perl, PHP, Python, C, LISP, Java, C#, and even Javascript), on three different databases; most of the APIs and tools are currently in alpha/beta state, not to mention the RDF spec itself, now heading towards last call. This was a challenging and rather frustrating experience at times.

Grr.

But, most of the tools and APIs were freely given and open source, supported by people who want nothing more than to provide nifty technologies for people to use.

Grr-eat.

TOC:

 

Chapter 1. Introduction
This chapter will introduce the book, as well as provide a brief history of RDF including current efforts as of the date the first draft of the book.

What exactly is RDF?
A Brief History
RDF and the Semantic Web
Current Specification Efforts
The RDF Specifications
When to use and not use RDF
RDF Controversies
Related Technologies
The RDF Primer

Chapter 2. RDF: Heart and Soul
Focuses on the Concepts and Semantics specifications

The Search for Knowledge
The RDF Triple
The RDF Graph
The URI
RDF Serialization: N-Triples
Datatypes
Talking RDF: Lingo and Vocabulary
Sub-Graphs
Graph and Not Ground
Entailment
Equality
Assertions

Chapter 3. Basics of RDF/XML
The major elements of the RDF syntax are introduced and discussed. Covers the syntax and test cases docs

Serializing RDF to XML
Nodes
Stripped Syntax
Properties
URIs, Qnames, and Abbreviations
The Type Property
RDF Blank Nodes
More on RDF Data Types
RDF Shortcuts
The RDF Test Cases

Chapter 4. Specialized RDF Relationships: Reification, Collections, and Containers
More complex constructs with some semantic challenges.

RDF Containers
Basic Container syntax
Typed node emulation
RDF Collections
What Containers and Collections ‘mean’
Reified Statements
An Example of Reification
The Necessity of Reification and Higher-Order Statements
A Shorthand Reification Syntax
Why Big Ugly?
Why Reify?

Chapter 5 Important concepts from the RDF Vocabulary
The RDF Schema provides the roadmap to creating an RDF vocabulary. The “rules” are covered, with examples to clarify the more complex topics.

RDF Schema: Defining the Metadata
Metadata’s Role in Existing Applications
RDF Schema: Metadata Repository
Core RDF Schema Elements
Overview of the RDF Core Classes
Demonstrations of the RDF Core Classes
Refining RDF Vocabularies with Constraints
RDF Schema Alternatives

Chapter 6. Defining RDF Data Schemas
This chapter provides coverage of defining a custom vocabulary for RDF. Discussion will also cover PICS, as an example, as well as other examples.

What do we mean by Vocabulary
Defining the Vocabulary Business and Scope
Defining the Vocabulary Elements
The PostCon Elements
Prototyping the Vocabulary
Adding in Repeating Values and a container
Formalizing the Vocabulary with RDFS
Another Example: The Dublin Core
An overview of the Dublin Core MetaData Element Set
Dublin Core in RDF/XML
The Qualified Dublin Core elements
Mixing Vocabularies
Using DC-dot to generate DC RDF
When Precision isn’t enough

Chapter 7. Ontologies: RDF Business Models
Why Ontology?
DAML+OIL
RDF and OWL

Section II – RDF Tools
Now that we know what it is, how can we work with it?

Chapter 8. Merging RDF with Other Technologies
Using RDF with other applications.

RDF and Links
RDF and SOAP
Generating RDF with XSLT
RDF and UML
RDF and SVG

Chapter 9. Editing, Parsing, Generating, Converting, and Browsing RDF
Browsers
BrownSauce
Parsers
ARP
Raptor RDF/XML Parser
ICS-FORTH Validating RDF Parser
Javascript RDF Parser
Wilbur
Editors
SMORE — Semantic Markup, Ontology, and RDF Editor
RDF Editor written in Java
Converters
Grove’s ConvertToRDF
Convert RDF to iCalendar (Dan Connolly) – RDF Calendar task force
DMOZ RDF Parser for MySQL

Chapter 10. Jena: A Java-Based RDF API
Overview of the Classes
The Underlying Parser
The Model
The Query
The Iterators
DAML+OIL
Creating and Serializing a model
Very Quick Simple Look
Encapsulating the Vocabulary in a Java Wrapper Class
Adding in more complex structures
Creating a Typed node
Creating a container
Parsing and Querying an RDF Document
Just doing a basic dump
Accessing specific values
In Memory versus Persistent Memory Model Storage
A Brief look at DAML+OIL in Jena

Chapter 11 RDF and the Three P’s

RDF/XML and Perl
Ginger Alliance PerlRDF
Model Persistence and Basic Querying
Serializing RDF/XML
Examining the Schema
RDFStore
The PHP XML RDF Classes
RDF-API
Class Overview
Creating an RDF Model
Parsing and Querying an RDF Model
PHP Classes for XML
Class overview
Rdql
Persistent RDF – rdql db
Python Support
RDFlib
Building a basic Model and Serializing
Parsing a model and queries
TripleStore and ZODB

Chapter 12 Querying RDF: RDF as Data
Basic relational syntax of RDF query languages
Querying with Jena
The Query Language
RDF Query-o-Matic
Querying with PHP
The Query Language
RDF Query-o-Matic light
Inkling–Querying RDF Data using SquishQL
Sesame
RDF Server (rdftp)
Versa RDF Querying Language

Chapter 13. A Brief look at other RDF Application Environments
Whatever works with XML, works with RDF/XML
Overview of Redland — a multi-language -based RDF Framework
Working with the Redland Framework
Redland’s language du jour – C
Using the Language APIs
Perl and Python
Redfoot
RDF and NET
C# RDF Parser
4Suite

Section III – RDF Goes to Work
We know what it is, we know how to use it, now list some of the uses.

Chapter 14. Subscription and Aggregation with RDF/RSS (RSS 1.0)
This chapter focuses on RSS, including how to expose content, including exposing content through userland, other sources. Chapter also covers Meerkat.

RSS: A quick History
RSS 1.0: A quick introduction
A Detailed Look at the Specification
Channel
Title, Link, Description
Items
Image
Textinput
Item
Extending the Specification through Modules
The RSS Modules
Core: Dublin Core, Syndication, Content
Extended
Brief look at RDF/RSS Aggregators
AmphetaDesk
Meerkat
Aggregating on a Mac
Creating your own RDF/RSS Content
(RDF/RSS isn’t only for news feeds)
Build your own RDF/RSS Consumer
PHP – using an XML API
Python – using an RDF API
Java – using a specialized RSS API
Perl – Ditto
Validating and Converting to RDF/RSS

Chapter 15. Mozilla: User Interface Development with XUL and RDF
Covers Mozilla’s use of RDF to process template data within XUL. Strong enough and significant enough to leave as separate chapter.
The Concepts behind XUL
A Brief Review of the XUL User Interfaces
Dynamic Table of Contents using XUL/RDF
Nested TOC Data

Chap 16. A World of Other Uses
FOAF: Friend-of-a-Friend
DMOZ Directory Outputs and the DMOZ parser
RDF Gateway, a commercial RDF Database
Chandler: RDF within an Open Source PIM
RDF and Adobe: XMP
Creative Commons license
Tucana KnowledgeStore (TKS)
A look at the RDF projects underway at Sourceforge

Appendix A. A Detailed Look at the RDF Grammar

Get permission from W3C to duplicate the RDF Grammar and productions

Appendix B. RDF Resources

URLs and notes to as many RDF resources as we can scrape together