Reddit’s Tips for Writers

A recent thread on Reddit asked for [“simple tips that make a huge difference in other people’s writing.”][1] Some interesting things are mentioned–read your work out loud, watch use of adverbs, etc.–but these eight tips from Kurt Vonnegut also got posted:

1. Use the time of a total stranger in such a way that he or she will not feel the time was wasted.
2. Give the reader at least one character he or she can root for.
3. Every character should want something, even if it is only a glass of water.
4. Every sentence must do one of two things — reveal character or advance the action.
5. Start as close to the end as possible.
6. Be a Sadist. No matter how sweet and innocent your leading characters, make awful things happen to them-in order that the reader may see what they are made of.
7. Write to please just one person. If you open a window and make love to the world, so to speak, your story will get pneumonia.
8. Give your readers as much information as possible as soon as possible. To hell with suspense. Readers should have such complete understanding of what is going on, where and why, that they could finish the story themselves, should cockroaches eat the last few pages.


Peer Review

Occasionally when I am reading about coding practices, I am struck by the richness and clarity which maintains what is essentially a writing process. I think there is something more to be examined there, and, perhaps once the boat book is done and the narrative project is underway, there will be time to consider how software writing is writing and what that may mean for how we think about writing.

All of this is occasioned, by the way, by a [post on StackExchange][se], about how to deal with code review in, what other programmers argue, is an unstructured review process. In the case, of the original question, a team member has his code reviewed by the assistant lead for the team, who makes changes without talking about the changes with the writer. The writer naturally wants to own his own code and to understand what he did wrong, but he also feels like the assistant lead occasionally makes corrections before a piece of code is completed — and so there may be “working errors” in the code (what writer he can’t commiserate over a terrible sentence, or paragraph even, that’s there as a placeholder?) — and occasionally adds code that the writer doesn’t feel is very readable. (This is all incredibly rich stuff for thinking about composition and writing in general, no?)

As I note above, other programmers basically respond that the individual involved, the assistant lead, is not so much the problem as the code review system itself. It’s worth thinking about the fact that the only time we offer writing experiences as structured as this in the university environment is in courses, and usually only in courses focused on writing. Sometimes, depending on the faculty member, we may offer such an experience to students working on theses and dissertations.

Why don’t we offer more? Because our infrastructure is so poor. Using a word processor with the commenting and reviewing features turned on is a first step, but it hardly allows the writer, and the reviewer, to compare versions of a document, to track changes across multiple iterations. Jonathan Goodwin and I took our first steps in this regard this past fall when we decided to compose our essay using *LaTeX* and used a *Git* repository hosted on [*Bitbucket*][bb]. (The repository is currently private, but we do plan to make it public.) *Wouldn’t it be exciting if every student began their university career with a repository that they maintained and with which various instructors and peers interacted, contributed, or reviewed over the course of their education?*

Towards that end, there were a couple of suggestions for *peer review* platforms made in the StackExchange thread that I thought I would note here. The first package mentioned is [Atlassian’s *Crucible*][ac], which I mention here first as well because it should work well with *BitBucket*, which is also by Atlassian. (And if you haven’t signed up for BitBucket, you should. It’s free for academics. The chief advantage over *GitHub* is, as noted above, the option to have private repositories.) More importantly, just attend to the way the elaborations possible in the review process offered by something like *Crucible*:

* Crucible provides configurable options to track and complete reviews (defined workflow, moderator, one or more participants).
* *Reviews are about comments.* Crucible supports fully threaded comments so teams can discuss code at different times and locations.
* Reviewers can navigate several revisions of a file under review. If a newer revision of a file is available, Crucible will indicate that the file is outdated, and provide a shortcut to quickly add the latest revision.
* Quickly create pre-commit reviews while you’re in the flow of coding from the command line–no logging into Crucible, no context switching.
* Some source (or any text) just needs to be discussed without a formal review process. Crucible provides ways to discuss code informally.
* To help stay on top of your reviews, you can: subscribe via email or RSS to review activity, including new comments, status change, or file additions; bookmark reviews or review comments as favorites to revisit them later.
* Sometimes developers forget about code reviews that need their attention. Automatically or manually notify reviewers who have not completed your code reviews. Set up reminders for reviews with due dates or manually “nudge” them to get their attention.
* All of this can be managed, and reviewed, through a dashboard.

That is a fantastic set of options, and, again, much of it is available either at a significant discount for academic institutions or for free for open source, non-profits, and classrooms. (See the [Pricing] page for details.)

Crucible is not the only game in town, and there are straight-up open source alternatives. One is [Review Board][rb]. Like Crucible it offers a dashboard that summarizes what an individual user (writer!) usually wants to know. It also hosts a diff viewer that allows you to see at a glance if things have simply been moved — a nice feature to have in any diff viewer.

Okay, there is a lot of terminology above that is going to be foreign to most humanists, and even a lot of scientists. E.g., repository (repo), commit(s), diff (short for difference). And the overviews for each of these packages, Crucible and Review Board, reveals that everything is in this weirdly unformatted form known as plain text, an equally strange term (and concept, unfortunately) for most non-coders.

My underlying argument is all this could, and should, change. I recognize that the kind of writing we do as scholars, and scientists, is different than the kind of writing done by software developers, but that shouldn’t stop us from adapting useful technologies when they present themselves. The argument for this is pretty straightforward: the computer was not invented as a writing tool, and yet almost everyone I know uses it as such. (And, in fact, we complain when our students don’t use it as a writing tool but as a distraction device.)

This is, obviously, a tentative first step in a much longer, I hope, argument. I can’t give it the attention I would like right now because I am in the middle of writing myself. While my next research project is focused on the intersections of narrative and ideology, I would like to take some time out to think about how “writing is writing.” For now, I am tagging this as such, *writingiswriting*. We’ll see what accrues to this tag over time.


Scrivener Tips

A number of my graduate students have taken the [Scrivener][] challenge and are finding their writing lives made much easier. Since I feel like there is a whole lot more to this application yet for me to learn, too, I am creating this post as a place to list various tips and usage scenarios that look interesting.

* The first thing that many writers find themselves doing, after perhaps re-arranging the deck furniture (sizing windows, setting the text zoom) is to set up their preferred typographic schema: type face (font), type size, line spacing, paragraph indentation, block quote citation, etc. If that’s the case, then Gwen Hernandez has a nice [run-down][] of how to make that scheme standard for all your new documents as well as how to convert existing documents to your scheme.
* The next thing most researchers in need of citation management want to do is to figure out how to use their preferred citation manager. Scrivener supports BookEnds and Sente out of the box, and it appears that Papers is quite workable. (I am currently testing Papers, having skipped Sente because it requires syncing through its own servers, at an additional cost and because Bookends seems to have developed so slowly. I have tried and tried to love Zotero, but it does not love me back, and so I am going to spend the money to see how well Papers works for me. And let’s not discuss EndNote, which is just too expensive for my regional-public-university-salary-frozen-for-the-past-eight-year’s budget.)
* **CMD + SHIFT + T** is your friend. It allows you to check your progress for a given session, day, or other period you specific. I write Monday through Friday, and my goal is 500 words a day. I have set the pop-up to calculate from midnight to midnight, so if I quite Scrivener, for whatever reason, during the say, then my count for the day is not lost. (It also means that if I leave it open overnight, I don’t get credit for the previous day’s work.) When things are going well, I can get more work done than that — sometimes averaging 1000 words a day at a stretch — but I regard 500 words as a reasonable average. For my own records, I’ll write down the day’s word count at the end of the day in the margins of my calendar.



I have more to say about the ideas found in this video as well as the ideas found in [a recent post by Scott Weingart][] — I especially want to think about his opening line where he deplores the dark corners of the humanities — but for now I’ll post this recent whiteboard animation by [the RSA][] (the Royal Society for the encouragement of Arts, Manufactures and Commerce):

And while I’m thinking about it: I am really keen to find an application that will allow one to create presentations that would, in essence, be based on a complete illustration, say an 11 x 17 tabloid-sized poster, but that would allow you to “navigate” it or pan and zoom to display small pieces at a time. I know [Prezi][] does this, but Prezi is very web-centric and access to their desktop application is an annual subscription. For those who are Mac users, you may know that [OmniGraffle Pro][] has a presentation mode, but it’s still built around the traditional presentation model of multiple slides, or in OG’s terminology, canvases. Apple’s [Keynote][] application will animate differences between slides, but you don’t end up with one common graphic as your output. (Speaking of which, Keynote’s print output options are abominably limited: PowerPoint is years ahead in this regard.)

[a recent post by Scott Weingart]:
[the RSA]:
[OmniGraffle Pro]:

Macbeth V.5

The complete quotation:

> She should have died hereafter;
There would have been a time for such a word.
To-morrow, and to-morrow, and to-morrow,
Creeps in this petty pace from day to day
To the last syllable of recorded time,
And all our yesterdays have lighted fools
The way to dusty death. Out, out, brief candle!
Life’s but a walking shadow, a poor player
That struts and frets his hour upon the stage
And then is heard no more: it is a tale
Told by an idiot, full of sound and fury,
Signifying nothing.

[Check out this example of Paul Graham composing “Startups in 13 Sentences.”]( You can pause, fast forward, rewind. Stypi was built for real-time editing with multiple users but it also lets you play back your typing and editing later so that you can “see” the nature of the composition. It’s like the iOS Brushes app for Words. On your computer.

Plague Doctors

I am reading Jeffrey Carver’s Eternity’s End, which features a version of The Flying Dutchman legend in it. (A bit too obviously — really, the allusion would have sufficed without constantly being told, “Hey, it’s a Flying Dutchman … in space!) A recent experiment in using a writing prompt had me re-writing Sherlock Holmes with the narrator, Watson, being an AI. I find myself fascinated by these kinds of revisions, and so I can’t help but wonder what one could do with the image and idea of plague doctors:

A Plague Doctor, by Faul Furst