Stuff Going On At The Ranch

In case folks are dying to read more of my technical writing, I’ve been writing a lot of material over at the Big Nerd Ranch Weblog, including some gems like:

• Notifications – registering and posting, Handling and spying
• Anatomy of a Bug Report
• String and String, what is String?
• A quieter Log
• Where does it go, George? (three places you can put instance variables)
• The Ranch at CocoaConf DC, 2012
• So, what next? (what to do after reading a book or taking a course)
• Beware the Cruftmonster
• NS-structs
• Editorial Rule-making
• Property List Serialization
• Actually finding a memory management error with Instruments
• BOOL’s sharp corners
• Both kinds of Cocoa
• Table Scanning
• A motivation for ivar decorations
• Why Protocols?, Protocols and Delegation (including a cheesy little world map view), and Adopting protocols in class extensions
• isEqual[ToString]: and going down a rabbit-hole
• NSError NoNo
• Objective-C Literals, and more of the same
• An easy to use block-based timing utility
• Some category pros and cons (hrm, the cat looks familiar)
• and finally an ARC Gotcha.

Well, OK, that’s everything, even the not-so-gemmy. For the forseeable future my geek writing will be over there, and I’ll reserve this weblog for cute Vikki pictures:

Scrivener for long-form technical writing

 

Every now and then I come across a software tool that Gets It. A tool that does everything right. A tool that is a joy to use. VoodooPad is one. MarsEdit is another. Scrivener is the latest to enter the pantheon of My Favorite Apps.  The last three big chunks of new stuff for AMOSXP(3), (GCD, using Instruments, and a re-write and major updating of NSFileManager) were organized and written in Scrivener, and then later converted to DocBook for inclusion in the book. In all, about 18,000 words worth of work.

Scrivener is a non-linear text editing environment. Rather than having, say, a chapter of a book in one single Word or Pages document, you can have each section or sub-section of that chapter in an entity. You can organize these entities in an outline, and Scrivener will automatically flow the text as if it were a larger document. Each entity can be as long or as short as it needs to be.

For example, this is the “binder”, the outline view, for the new GCD chapter:

It has all of the sections of the chapter. If I’m wanting to edit the text for Dispatch Groups, I can select it in the Binder and focus in only on that text. If I wanted to make sure that the text flows into and out of that section, I can multi-select Time, Dispatch Groups, and Semaphores, and see those three sections of text in one editing panel, with subtle separators between the sections. If I decide that I really should talk about queues before terminology, I can just drag the entity and rearrange things. This feature alone, to me, is worth the low price of admission ($45).  Doing major surgery like that in a single document is fraught with peril.  With Scrivener, it’s drag and drop.  Don’t like it?  Undo it.

In addition to seeing the text, and a standard wordprocesor-style outline view (which I don’t use), there’s a cool corkboard mode. I originally thought it was silly and gratuitous, but I eventually found it to be a nice (and fun) way to play with the organization of the document. The corkboard mode also shows metadata, such as a high-level description of the section, its draft status, and other things:

You can see that most of the chapters are First Draft, meaning that I’ve gurgitated out the text, did an editing pass, and it’s ready to make the one-way trip to DocBookland for markup, professional editing, and indexing. A couple are “In Progress”, meaning they’re being worked on but not ready to see the light of day. I can tell at a glance what shape the chapter is in. You can rearrange the document here too. Clicking and dragging the note cards is reflected in the outline view, and hence in your overall body of text.

One of the cool things is the text contents of the note cards. The title of the card matches the title in the Binder view. Simple enough. But you can also have a description, independent from the actual contents of the section. Scrivener gives you a lot of opportunity for out-of-band data. With traditional word processing environments, pretty much everything that’s in the document is part of the flow of text, except maybe things like reviewer’s comments. Scrivener has lots of opportunities for attaching meaningful metadata to sections: add tags, arbitrary keywords, arbitrary long notes and descriptions. Fiction writers can tag scenes with characters, themes, locations, smells, etc. Later on they can do searches to see all the scenes a particular character is in, or what sections concentrate on badger foreshadowing.  I didn’t use much metadata stuff, mainly the note card descriptions and the status.

In addition to the “Draft” area, which has all the text of your document in the little entity files, you can have any number of non-publishing hierarchies of stuff. I do most of my research in VoodooPad – it’s where all the raw information goes as I read technical docs, research on the web, and write test apps. Then I bring it over piecemeal into Scrivener as I suss out how things should be organized, and figure out what needs to be included and what can be left on the floor. Here’s the research part for Instruments:

Each of the texty-looking icons is the equivalent of a text file. You can have whatever text you want there, formatted how you want, embedded images, etc. Kind of like Keynote, these text docs aren’t the leaves of the tree. They’re also the internal nodes. The “Different Kinds of Instruments” text doc actually has three child documents too, each with their own text. I can select “Different Kinds of Templates”, and see its text, along with the children’s text in-line (if I want). There are also images, in this case screenshots, that are part of the “document” hierarchy. As I was writing the chapter, I’d be migrating important information from Voodoo Pad, arranging and rearranging entities so the order of presentation made sense. I wrote a fair amount of the chapter’s prose here. As I took screen shots, I added them as child nodes to the text they would appear in. This way they’d carried along as I rearranged chapters. It’s a very powerful, yet easy to use system.

One odd thing about Scrivener is that it is actually fun to write in. No other text editor feels as responsive as Scriv’s. It’s hard to describe, but typing just feels better than in other apps. The obligatory full-screen mode is nice when you have to concentrate to Get Things Done.  Also, I am a huge fan of the “typewriter” mode. This centers the line being edited in the window. I can have a tall window so I can get lots of context, but when I’m actually typing and editing, the text is in the sweet-spot of my eyeglasses.

Indie developers would should take a good look at Scrivener’s website.  I spent a long time reading the materials, and looking at the demo movies.  They’re all very targeted.  “Here is a cool feature, here’s how it fits in with the rest of the product and here is how you would use it.”  After awhile, I got a very good sense of the how the product worked, and what particular features would make my life easier.  I had zero problems getting Real Work done immediately after download.

So, if you’re into any kind of long-form writing, whether it be novels for NaNoWriMo or technical books, or even the occasional complicated blog post, I recommend you check out Scrivener. It does so much Right that it is a joy to use.

How I Got Started In Programming

The redoubtable AnneKate™ tagged me with a narcissitic brain-dump meme, How I Got Started Programming, so I figured I’d chime in. Usually I don’t do that stuff here, but hey, it’s my blog, I can me me me me if I want to.

How old were you when you started programming?

Sixth grade. Which would put me around 12 years old maybe? My dad brought home an Apple ][ (amazing how many stories like this start off with that machine), intending to do Typical Computer Things like track finances and write simulations of radiation-resistent DNA (my Dad’s awesome), but I noticed that it could play GAMES, and I glommed on to it. Dad got occasional visitation rights, but for the most part, the machine was all mine.

It was a super spiffy version, too. It had 48K, plus Applesoft BASIC on a card (Integer BASIC on the motherboard). To switch between languages, you powered-down, flipped the switch, and powered back up. (this was before DOS 3.3). Eventually the machine got a Language Card (16K expansion).

How did you get started in programming?

Typing in programs from magazines and books. This was the time when print publications (remember those?) would have complete program listings. I learn best by by eye -> hands -> screen -> eye -> brain, and this is how I learned programming. Actually, where I learned debugging, since you learn more by making (and finding, and fixing) misteaks than you do by doing things perfectly the first time. At least that’s what I keep telling myself.

What was your first language?

Apple ][ Integer BASIC. Later Applesoft, and then the UCSD Pascal system.

What was the first real program you wrote?

Where “real” is something non-trivial, and not something I typed in from a magazine. It was one my Dad designed, and I implemented. It was essentially a quality assurance database system for a Radiology department. Diagnoses could be entered, and then later correlated with reports from Pathology. Or something like that. As far as I was concerned, it was “type stuff in, save it to disk”, and then periodically run the worlds most inefficient multi-device sort. But it was cool seeing three Disk ][ units hooked up to a machine, all running.

It was at this time I learned what flowcharts were (remember those?), sigma notation, and basic algorithms and data structures.

What languages have you used since you started programming?

Roughly chronoillogical order, favorites starred

Integer BASIC (*), AppleSoft BASIC (*), UCSD Pascal (*), FORTRAN IV (under UCSD Pascal), VAX FORTRAN, VAX assembly, VAX BASIC, VMS DCL, Dbase ///, Turbo BASIC, Mac/TML Pascal (*), Hypertalk, Object Pascal, C (*), C++, Newtonscript, /bin/sh, /bin/csh, emacs lisp, Tcl (*), Perl, Oracle SQL, PL/SQL, PHP, Objective-C (*), /bin/bash, Javascript, Pythong, Java, Sawzall. HTML (XML and generic SGML) if you count those as languages.

Badgers, or Wombats?

Badgers, definitely.

What was your first professional programming gig?

Visix Software (R.I.P.) We did a cross-platform toolkit called “Galaxy”. It ruled™, and was definitely ahead of its time. Its geometry management system has not been approached by anything I’ve seen since.

I started off in tech support answering questions about network configuration for our license server and X11 Font Paths for our Looking Glass product. Eventually worked my way up to Señor Software Engineer working on some important parts of the product. Also, because of Visix, I spent four months on Wall Street.

My first “will program for food” was a couple of summers and Christmas vacations during college at the Little Rock VA Hospital, assembling PC-clones from spare parts, and building some software tools for the department. One was an elaboration of the previous medical system (this time in a “real” database, Dbase ///), and an isotope tracking system. I couldn’t really be paid, so I was officially a volunteer. If I was there for four or more hours, I got a cafeteria meal voucher, which was *just enough* for a cheeseburger, onion rings, and a coke. It was the only non-lethal thing there.

If you knew then what you know now, would you have started programming?

Hell yes! I’m having the time of my life, and I get paid for it.

If there is one thing you learned along the way that you would tell new developers, what would it be?

This is more generic life advice, but something I feel strongly about: Surround yourself with people that are smarter and more talented than you, and learn from them. See what they do, figure out why they do it. Ask questions. Bask in their greatness and absorb everything.

At Visix, I spent a big chunk of time hours and three whiteboards going through the Galaxy “Class Manager”, figuring out how it worked (which was a combination of C++-style vtables and Objective-C runtime lookup, but all in vanilla C, with a lot of macro magic).

What’s the most fun you’ve ever had programming?

At Visix, in the bootstrap days of Galaxy. I wrote a lot of demo programs and sample code, in addition to doing the “List Manager” (think Excel, but without the calculation engine). There were a lot of times I’d be working all night on some fun thing (like a graphics demo that needed scrolling, but we didn’t have scroll bars implemented yet, so I wrote a little joystick thingie). My favorite times were hacking on something fun, looking out the window, and watching the sun rise. It was magical.

Thanks AnneKate, that was a fun stroll down memory lane. Now get off my lawn.

First Post!

Greetings,

As annoyed as I get with blogs that devolve into the meta (look at my redesign! I just changed blog hosts!), I must consume the humble pie and say I’m moving the Borkware Miniblog to WordPress, mainly so I can use the most excellent Red Planet Mars Edit editor. Web forms just don’t do it for me any more. Hopefully just setting up a redirect from my previous blog location to this one will work correctly for both of my subscribers.