Writing Online

Those damn flies

Unlike some people, I don't find collapsed outlines to be easily comprehensible. I've looked at Frontier several times over the years, and keep not using it for this reason. It's not obvious where things are, or what does what. I'm more comfortable with the blank sheet of paper that is AppleScript or Perl. I still don't know where to go, but it's easier for me to read what others have written.

In any case, the weblogNeighborhood tool is not setting the style of some sites to bold, despite those sites seeming to have met the criteria necessary. The tool bolds the site if the site contains the results of the headLinks macro. More specifically, if the site contains a link element thusly

<link rel="subscriptions" type="text/x-opml" title="Subscriptions" href="http://radio.weblogs.com/0001015/gems/mySubscriptions.opml">

then the harvester bit of the tool can follow that link and examine the subscriptions list. If the harvester can follow that link, it will then flip a boolean (true or false) value stored for the site in the radio.user.weblogNeighborhood.neighbors table. Then if the value of radio.user.weblogNeighborhood.neighbors.urlOfTheSite.flharvested is true, the saveReportHtml routine will bold the site when it writes the HTML.

But it's not doing this consistently.

Note the differences here, here, and here, in how the weblogNeighborhood tool highlights some sites and not others. Sam Ruby, Jenny Levine, and Jon Udell, among others, should all be highlighted.

Others may not have been harvested because they don't have the required <link> element in their HTML page, or if there was an error reading or parsing their page, or if they were in the last level traversed.

Or?

12:28:51 PM # Google It!
categories: Writing Online

Writing Instructions

Brent Simmons writes “... it’s good for engineers and architects to write docs because it makes the software better.”

....

Engineers, architects, writers, and others should collaborate on documentation. The collaboration should be based upon engineers and architects serving as subject matter experts for the writer.

....

Engineers can’t do it (at least not for their own projects). They know too much.

[ARTS & FARCES internet]

They're both right. One of the reasons why programmer types don't write good documentation is that they, like someone giving directions to his house, assume too much familiarity on the part of the reader. Writing documentation, and having it used by someone else, reveals the missing steps. It also reveals the way to better software.

Remember that class in BASIC on the TRS-80 in high school? The computer does everything you tell it to, exactly as you say, but if you don't tell it, it can't do it. You cannot skip steps.

11:48:16 AM # Google It!
categories: Learning, Writing Online, System Administration