Archive for the ‘Writing’ Category

Tiny Narratives – Upgrade Your Writing

Thursday, April 13th, 2017

8 steps to upgrade your everyday news stories with ‘tiny narratives’ by Katia Savchuk.

From the post:

BEFORE BETH SCHWARTZAPFEL became a staff writer for The Marshall Project three years ago, she spent a decade as a freelance magazine writer. She got used to spinning 4,000-word narratives for places like Mother Jones and the Boston Review. When she arrived at the nonprofit newsroom, which covers criminal justice, Schwartzapfel found herself tackling an entirely different animal: breaking news and hard-hitting features that put the facts center stage.

Schwartzapfel considered how she could bring her storytelling chops to these new formats. Her answer was what she calls “tiny narratives”: compact anecdotes, sometimes only a few lines long, scattered throughout a fact-driven article. “I think of them as raisins in oatmeal, or the signs people hold on the sidelines of a marathon. They’re little surprises or jolts of pleasure to remind people of what they’re reading and why it matters,” she explained in a session at the Power of Narrative Conference at Boston University in late March.

Those nuggets of humanity can help keep readers on the page at a time when news organizations are scrambling for the public’s attention. But it isn’t easy to do well. Injecting narrative elements into a news or investigative story can bring unnecessary clutter or overwhelm the essential facts.

Here are tips from Schwartzapfel and other speakers at the conference about how to get “tiny narratives” right.
… (emphasis in original)

A series of great tips, but if you want more examples of Schwartzapfel’s writing, try Beth Schwartzapfel, Staff Writer.

I count fifty-five (55) stories.

More than enough for a Hunter Thompson exercise of re-typing great stories:

Posted by Brian John Spencer in Hunter S. Thompson – Typing out the work of the best writers.

Think of Thompson’s approach as developing “muscle and verbal cadence” memory.

I’m much more likely to try that with Schwartzapfel’s stories than with XQuery, but it would be an interesting exercise in both cases.

😉

Papers we Scrutinize: How to critically read papers

Thursday, April 13th, 2017

Papers we Scrutinize: How to critically read papers by Tomas Petricek.

From the post:

As someone who enjoys being at the intersection of the academic world and the world of industry, I’m very happy to see any attempts at bridging this harmful gap. For this reason, it is great to see that more people are interested in reading academic papers and that initiatives like Papers We Love are there to help.

There is one caveat with academic papers though. It is very easy to see academic papers as containing eternal and unquestionable truths, rather than as something that the reader should actively interact with. I recently remarked about this saying that “reading papers” is too passive. I also mentioned one way of doing more than just “reading”, which is to write “critical reviews” – something that we recently tried to do at the Salon des Refusés workshop. In this post, I would like to expand my remark.

First of all, it is very easy to miss the context in which papers are written. The life of an academic paper is not complete after it is published. Instead, it continues living its own life – people refer to it in various contexts, give different meanings to entities that appear in the paper and may “love” different parts of the paper than the author. This also means that there are different ways of reading papers. You can try to reconstruct the original historical context, read it according to the current main-stream interpretation or see it as an inspiration for your own ideas.

I suspect that many people, both in academia and outside, read papers without worrying about how they are reading them. You can certainly “do science” or “read papers” without reflecting on the process. That said, I think the philosophical reflection is important if we do not want to get stuck in local maxima.

Petricek goes on to define three (3) different ways to read a paper, using A Formulation of the Simple Theory of Types by Alonzo Church.

Worth reading and following, but consider more concrete guidance as well:

The requirements to make reading and peer review useful activities are well known.

Only you can prevent the failure to meet those requirements in your case. Yes?

The Science of Scientific Writing

Saturday, June 25th, 2016

The Science of Scientific Writing by George D. Gopen and Judith A. Swan.

From the paper:

Science is often hard to read. Most people assume that its difficulties are born out of necessity, out of the extreme complexity of scientific concepts, data and analysis. We argue here that complexity of thought need not lead to impenetrability of expression; we demonstrate a number of rhetorical principles that can produce clarity in communication without oversimplifying scientific issues. The results are substantive, not merely cosmetic: Improving the quality of writing actually improves the quality of thought.

The fundamental purpose of scientific discourse is not the mere presentation of information and thought, but rather its actual communication. It does not matter how pleased an author might be to have converted all the right data into sentences and paragraphs; it matters only whether a large majority of the reading audience accurately perceives what the author had in mind. Therefore, in order to understand how best to improve writing, we would do well to understand better how readers go about reading. Such an understanding has recently become available through work done in the fields of rhetoric, linguistics and cognitive psychology. It has helped to produce a methodology based on the concept of reader expectations.

What? Evidence-based authoring? Isn’t that like evidence-based interface design?

Trying to communicate with readers on their own terms and not forcing them to tough it out?

Next thing you know, Gopen will be saying that failures to communicate in writing, are the author’s fault!

Wait!

He does:


On first reading, however, many of us arrive at the paragraph’s end without a clear sense of where we have been or where we are going. When that happens, we tend to berate ourselves for not having paid close enough attention. In reality, the fault lies not with us, but with the author. (page 9 of the pdf)

“The Science of Scientific Writing” is a great authoring by example guide.

Spending time with it can only make you a better writer.

You will be disappointed if you try to find this item from the bibliography:

Gopen, George D. 1990. The Common Sense of Writing: Teaching Writing from the Reader’s Perspective. To be published.

Worldcat.org reports one (1) copy of The Common Sense of Writing: Teaching Writing from the Reader’s Perspective is held by the Seattle University
Law Library. Good luck!

I located an interview with Dr. Gopen, which identifies these two very similar volumes:

Expectations: Teaching Writing from the Reader’s Perspective by George D. Gopen, ISBN-13: 978-0205296170, at 416 pages, 2004. (The complete story.)

The Sense of Structure: Writing from the Reader’s Perspective by George D. Gopen, ISBN-13: 978-0205296323, at 256 pages, 2004. (A textbook based on “Expectations….”)

Neither volume is cheap but when I do order, I’m going for Expectations: Teaching Writing from the Reader’s Perspective.

In the mean time, there’s enough poor writing on the Internet to keep me practicing the lessons of The Science of Scientific Writing for the foreseeable future.

Writing Challenge: Short Science!

Wednesday, April 20th, 2016

Welcome to Short Science!

From the webpage:

Sometimes research papers are hard to understand because of nomenclature, unclear writing, unnecessary formalisms, etc… It is useful to ask an expert in the field to summarize the intuition behind a paper to help you understand it. Have you every finally understood a paper and then said “That’s it?” The goal is that you have those “That’s it?” moments without having to spend days reading the paper!

Short Science allows researchers to publish paper summaries that are voted on and ranked until the best and most accessible summary has been found! The goal is to make all the seminal ideas in science accessible to the people that want to understand them.

Everyone can write summaries for any paper that exists in our database. It is easy to think you know enough about a paper until you try to write something public about it. You may discover that you don’t understand the concept when you try to write a short accessible summary about it.

Short Science is where Einstein puts you to the test “If I can’t explain it simply, I don’t understand it well enough.” Do you understand a paper well enough? Prove it to yourself by writing a summary for it! Also, write summaries of your own papers to help people to understand it and gain impact!

If you are looking for an authoring/writing challenge, you have found the place!

Not that I need another authoring venue but this looks like fun. Not to mention a way to get external validation.

Enjoy!

Email Write Order

Friday, April 8th, 2016

Email Write Order by David Sparks.

This is more of a reminder to me than you but I pass it along in case you are interested.

From the post:

I’ve always had a gripe with email application developers concerning the way they want us to write emails. When you go to write an email, the tab order is all out of whack.

The default write order starts out with you selecting the recipient for your message, which makes enough sense, but then everything goes off the rails. Next, it wants you to type in the subject line for a message you haven’t written yet. Because you haven’t written the message, there is a bit of mental friction between us getting our thoughts together and making a cogent subject line at that time, so we skip it or just leave it with whatever the mail client added (e.g., “re: re: re: re: re: That Thing”).

Next, the application wants you to write the body of your message. Rarely does the application even prompt you to add an attachment, which means about half the time you’ll forget to add an attachment. Because the default write order is all out of whack, so are the messages we often send using it. It makes a lot more sense to add attachments next and then write the body of the message before filling out the subject line and sending. I’ve got an alternative write order that makes a lot more sense.

Suggestion: Try David’s alternative order for the next twenty or so emails you send.

Whether you bite on his $9.99 Email Field Guide or not, I think you will find the alternate order a useful exercise.

Enjoy!

why I try to teach writing when I am supposed to be teaching art history

Wednesday, December 9th, 2015

why I try to teach writing when I am supposed to be teaching art history

From the post:

My daughter asked me yesterday what I had taught for so long the day before, and I told her, “the history of photography” and “writing.” She found this rather funny, since she, as a second-grader, has lately perfected the art of handwriting, so why would I be teaching it — still — to grown ups? I told her it wasn’t really how to write so much as how to put the ideas together — how to take a lot of information and say something with it to somebody else. How to express an idea in an organised way that lets somebody know what and why you think something. So, it turns out, what we call writing is never really just writing at all. It is expressing something in the hopes of becoming less alone. Of finding a voice, yes, but also in finding an ear to hear that voice, and an ear with a mouth that can speak back. It is about learning to enter into a conversation that becomes frozen in letters, yes, but also flexible in the form of its call and response: a magic trick that has the potential power of magnifying each voice, at times in conflict, but also in collusion, and of building those voices into the choir that can be called community. I realise that there was a time before I could write, and also a time when, like my daughter, writing consisted simply of the magic of transforming a line from my pen into words that could lift off the page no different than how I had set them down. But it feels like the me that is me has always been writing, as long as I can remember. It is this voice, however far it reaches or does not reach, that has been me and will continue to be me as long as I live and, in the strange way of words, enter into history. Someday, somebody will write historiographies in which they will talk about me, and I will consist not of this body that I inhabit, but the words that I string onto a page.

This is not to say that I write for the sake of immortality, so much as its opposite: the potential for a tiny bit of immortality is the by product of my attempt to be alive, in its fullest sense. To make a mark, to piss in the corners of life as it were, although hopefully in a slightly more sophisticated and usually less smelly way. Writing is, to me, the greatest output for the least investment: by writing, I gain a voice in the world which, like the flap of a butterfly’s wing, has the potential to grow on its own, outside of me, beyond me. My conviction that I should write is not so much because I think I’m better or have more of a right to speak than anybody else, but because I’m equally not convinced that anybody, no matter what their position of authority, is better or has more of an authorisation to write than me.

Writing is the greatest power that I can ever have. It is also an intimate passion, an orgy, between the many who write and the many who read, excitedly communicating with each other. For this reason it is not a power that I wish only for myself, for that would be no more interesting than the echo chamber of my own head. I love the power that is in others to write, the liberty they grant me to enter into their heads and hear their voices. I love our power to chime together, across time and space. I love the strange ability to enter into conversations with ghosts, as well as argue with, and just as often befriend, people I may never meet and people I hope to have a chance to meet. Even when we disagree, reading what people have written and taking it seriously feels like a deep form of respect to other human beings, to their right to think freely. It is this power of voices, of the many being able of their own accord to formulate a chorus, that appeals to the idealist deep within my superficially cynical self. To my mind, democracy can only emerge through this chorus: a cacophanous chorus that has the power to express as well as respect the diversity within itself.

A deep essay on writing that I recommend you read in full.

There is a line that hints at a reason for semantic diversity data science and the lack of code reuse in programming.

My conviction that I should write is not so much because I think I’m better or have more of a right to speak than anybody else, but because I’m equally not convinced that anybody, no matter what their position of authority, is better or has more of an authorisation to write than me.

Beyond the question of authority, whose writing do you understand better or more intuitively, yours or the writing or code of someone else? (At least assuming not too much time has gone by since you wrote it.)

The vast majority of use are more comfortable with our own prose or code, even though it required the effort to transpose prose or code written by others into our re-telling.

Being more aware of the nearly universal casting of prose/code to be our own, should help us acknowledge the moral debts to others and to point back to the sources of our prose/code.

I first saw this in a tweet by Atabey Kaygun.

Authorea

Friday, May 22nd, 2015

Authorea is the collaborative typewriter for academia.

From the website:

Write on the web.
Writing a scientific article should be as easy as writing a blog post. Every document you create becomes a beautiful webpage, which you can share.
Collaborate.
More and more often, we write together. A recent paper coauthored on Authorea by a CERN collaboration counts over 200 authors. If we can solve collaboration for CERN, we can solve it for you too!
Version control.
Authorea uses Git, a robust versioning control system to keep track of document changes. Every edit you and your colleagues make is recorded and can be undone at any time.
Use many formats.
Authorea lets you write in LaTeX, Markdown, HTML, Javascript, and more. Different coauthors, different formats, same document.
Data-rich science.
Did you ever wish you could share with your readers the data behind a figure? Authorea documents can take data alongside text and images, such as IPython notebooks and d3.js plots to make your articles shine with beautiful data-driven interactive visualizations.

Sounds good? Sign up or log in to get started immediately, for free.

Authorea uses a gentle form of open source persuasion. You can have one (1) private article for free but unlimited public articles. As your monthly rate goes up, you can have an increased number of private articles. Works for me because most if not all of my writing/editing is destined to be public anyway.

Standards are most useful when they are writ LARGE so private or “secret” standards have never made sense to me.

Unker Non-Linear Writing System

Thursday, April 23rd, 2015

Unker Non-Linear Writing System by Alex Fink & Sai.

From the webpage:

non-linear

“I understood from my parents, as they did from their parents, etc., that they became happier as they more fully grokked and were grokked by their cat.”[3]

Here is another snippet from the text:

Binding points, lines and relations

Every glyph includes a number of binding points, one for each of its arguments, the semantic roles involved in its meaning. For instance, the glyph glossed as eat has two binding points—one for the thing consumed and one for the consumer. The glyph glossed as (be) fish has only one, the fish. Often we give glosses more like “X eat Y”, so as to give names for the binding points (X is eater, Y is eaten).

A basic utterance in UNLWS is put together by writing out a number of glyphs (without overlaps) and joining up their binding points with lines. When two binding points are connected, this means the entities filling those semantic roles of the glyphs involved coincide. Thus when the ‘consumed’ binding point of eat is connected to the only binding point of fish, the connection refers to an eaten fish.

This is the main mechanism by which UNLWS clauses are assembled. To take a worked example, here are four glyphs:

non-linear2

If you are interested in graphical representations for design or presentation, this may be of interest.

Sam Hunting forwarded this while we were exploring TeX graphics.

PS: The “cat” people on Twitter may appreciate the first graphic. 😉

The Sense of Style [25 December 2014 – 10 AM – C-SPAN2]

Tuesday, December 23rd, 2014

Steve Pinker discussing his book The Sense of Style: The Thinking Person’s Guide to Writing in the 21st Century.

From the description:

Steven Pinker talked about his book, The Sense of Style: The Thinking Person’s Guide to Writing in the 21st Century, in which he questions why so much of our writing today is bad. Professor Pinker said that while texting and the internet are blamed for developing bad writing habits, especially among young people, good writing has always been a difficult task.

The transcript, made for closed captioning, will convince you of the power of paragraphing if you attempt to read it. I may copy it, watch the lecture Christmas morning, insert paragraphing and ask CSPAN if they would like a corrected copy. 😉

One suggestion for learning to write (like learning to program), that I have heard but never followed, is to type out text written by known good writers. As you probably suspect, my excuse is a lack of time. Perhaps that will be a New Year’s resolution for the coming year.

Becoming a better writer automatically means you will be communicating better with your audience. For some of us that may be a plus or a negative. You have been forewarned.

Enjoy!


In case you miss the broadcast, I found the video archive of the presentation. Nothing that will startle you but Pinker is an entertaining speaker.

I am watching the video early and Pinker points out an “inherent problem in the design of language.” [paraphrasing] We hold knowledge in a semantic network in our brains but when we use language to communicate some piece of that knowledge, the order of words in a sentence has to do two things at once:

* Serve as a code for meaning (who did what to whom)

* Present some bits of information to the reader before others (affects how the information is absorbed)

Pinker points out that passive voice allows better prose. Focus remains on the subject. (Is prevalent in bad prose but Pinker argues that is due to the curse of knowledge.)

Question: Do we need a form of passive voice in computer languages? What would that look like?

How Scientists Are Learning to Write

Sunday, December 14th, 2014

How Scientists Are Learning to Write by Alexandra Ossola.

From the post:

The students tried not to look sheepish as their professor projected the article on the whiteboard, waiting for their work to be devoured by their classmates. It was the second class for the nine students, all of whom are Ph.D. candidates or post-doctoral fellows. Their assignment had been to distill their extensive research down to just three paragraphs so that the average person could understand it, and, as in any class, some showed more aptitude than others. The piece on the board was by one of the students, a Russian-born biologist.

The professor, the journalist and author Stephen Hall (with whom I took a different writing workshop last year), pointed to the word “sequencing.” “That’s jargon-ish,” he said, circling it on the board. “Even some people in the sciences don’t have an intuitive understanding of what that means.” He turned to another student in the class, an Italian native working on his doctorate in economics, for confirmation. “Yes, I didn’t know what was going on,” he said, turning to the piece’s author. The biology student wrote something in her notebook.

Why is better writing important?:

But explaining science is just as valuable for the lay public as it is for the scientists themselves. “Science has become more complex, more specialized—every sub-discipline has its own vocabulary,” Hall said. Scientists at all levels have to work hard to explain niche research to the general public, he added, but it’s increasingly important for the average person to understand. That’s because their research has become central to many other elements of society, influencing realms that may have previously seemed far from scientific rigors.

Olivia Wilkins, a post-doctoral fellow who studies plant genetics at New York University’s Center for Genomics and Systems Biology, recently took Hall’s four-session workshop. She wanted to be a better writer, she said, because she wanted her research to matter. “Science is a group effort. We may be in different labs at different universities, but ultimately, many of us are working towards the same goals. I want to get other people as excited about my work as I am, and I believe that one of the ways to do this is through better writing.”

How about that? Communicating with other people who are just as bright as you, but who don’t share the same vocabulary? Does that sound like a plausible reason to you?

I really like the closer:

“…Writing takes a lot of practice like anything else—if you don’t do it, you don’t get better. (emphasis added)

I review standards and even offer editing advice from time to time. If you think scientists aren’t born with the ability to write, you should check out standards drafts by editors unfamiliar with how to write standards.

Citations in a variety of home grown formats, to publications that may or may not exist or be suitable for normative citation, to terminology that isn’t defined, anywhere, to contradictions between different parts, to conformance clauses that are too vague for anyone to know what is required, and many things in between.

If anything should be authored with clarity, considering that conformance should make applications interoperable, it is IT standards. Take the advice in Alexandra’s post to heart and seek out a writing course near you.

I edit and review standards so ping me if you want an estimate on how to improve your latest standard draft. (References available on request.)

I first saw this in a tweet by Gretchen Ritter.

Beyond You’re vs. Your: A Grammar Cheat Sheet Even The Pros Can Use

Friday, November 21st, 2014

Beyond You’re vs. Your: A Grammar Cheat Sheet Even The Pros Can Use by Hayley Mullen.

From the post:

Grammar is one of those funny things that sparks a wide range of reactions from different people. While one person couldn’t care less about colons vs. semicolons, another person will have a visceral reaction to a misplaced apostrophe or a “there” where a “their” is needed (if you fall into the latter category, hello and welcome).

I think we can still all agree on one thing: poor grammar and spelling takes away from your message and credibility. In the worst case, a blog post rife with errors will cause you to think twice about how knowledgeable the person who wrote it really is. In lesser cases, a “then” where a “than” should be is just distracting and reflects poorly on your editing skills. Which is a bummer.

More than the ills mentioned by Hayley, poor writing is hard to understand. Using standards or creating topic maps is hard enough without having to decipher poor writing.

If you already write well, a refresher never hurts. If you don’t write so well, take Hayley’s post to heart and learn from it.

There are errors in standards that tend to occur over and over again. Perhaps I should write a cheat sheet for common standard writing errors. Possible entries: Avoiding Definite Article Abuse, Saying It Once Is Enough, etc.

Why Academics Stink at Writing [Programmers Too]

Saturday, October 4th, 2014

Why Academics Stink at Writing by Steven Pinker.

From the post:

Together with wearing earth tones, driving Priuses, and having a foreign policy, the most conspicuous trait of the American professoriate may be the prose style called academese. An editorial cartoon by Tom Toles shows a bearded academic at his desk offering the following explanation of why SAT verbal scores are at an all-time low: “Incomplete implementation of strategized programmatics designated to maximize acquisition of awareness and utilization of communications skills pursuant to standardized review and assessment of languaginal development.” In a similar vein, Bill Watterson has the 6-year-old Calvin titling his homework assignment “The Dynamics of Inter­being and Monological Imperatives in Dick and Jane: A Study in Psychic Transrelational Gender Modes,” and exclaiming to Hobbes, his tiger companion, “Academia, here I come!”

Steven’s analysis applies mostly to academic writing styles, although I have suffered through more than one tome in CS that apologies for some topic X being in another chapter. Enough already, just get on with it. Needed a severe editing which would have left it shorter and an easier read.

Worth the read if you try to identify issues in your own writing style. Identifying errors in the writing style of others won’t improve your writing.

I first saw this in a twee by Steven Strogatz

PS: Being able to communicate effectively with others is essential to marketing yourself or products/services.

Hemingway App

Friday, April 11th, 2014

Hemingway App

We are a long way from something equivalent to Hemingway App for topic maps or other semantic technologies but it struck me that may not always be true.

Take it for a spin and see what you think.

What modifications would be necessary to make this concept work for a semantic technology?

Writing about Math…

Tuesday, February 18th, 2014

Writing about Math for the Perplexed and the Traumatized by Steven Strogatz.

From the introduction:

In the summer of 2009 I received an unexpected email from David Shipley, the editor of the op-ed page for the New York Times. He invited me to look him up next time I was in the city and said there was something he’d like to discuss.

Over lunch at the Oyster Bar restaurant in Grand Central Station, he asked whether I’d ever have time to write a series about the elements of math aimed at people like him. He said he’d majored in English in college and hadn’t studied math since high school. At some point he’d lost his way and given up. Although he could usually do what his math teachers had asked of him, he’d never really seen the point of it. Later in life he’d been puzzled to hear math described as beautiful. Could I convey some of that beauty to his readers, many of whom, he suspected, were as lost he was?

I was thrilled by his proposition. I love math, but even more than that, I love trying to explain it. Here I’d like to touch on a few of the writing challenges that this opportunity entailed, along with the goals I set for myself, and then describe how, by borrowing from three great science writers, I tried to meet those challenges. I’m not sure if any of my suggestions will help other mathematicians who’d like to share their own love of math with the public, but that’s my hope.

If you are looking for tips and examples of how to explain computer science topics, you have arrived!

Not only is this essay by Strogatz highly useful and entertaining, you can also consult his fifteen (15) part series on math that appeared in the New York Times.

The New York Times series ended in 2010 but you can following Steven at: @stevenstrogatz and at RadioLab.

I first saw this in a tweet by Michael Nielsen.

BTW, if you have contacts at the New York Times, would you mention that including hyperlinks for Twitter handles and websites is a matter of common courtesy? Thanks!

The Scourge of Unnecessary Complexity

Thursday, December 19th, 2013

The Scourge of Unnecessary Complexity by Stephen Few.

From the post:

One of the mottos of my work is “eloquence through simplicity:” eloquence of communication through simplicity of design. Simple should not be confused with simplistic (overly simplified). Simplicity’s goal is to find the simplest way to represent something, stripping away all that isn’t essential and expressing what’s left in the clearest possible way. It is the happy medium between too much and too little.

While I professionally strive for simplicity in data visualization, I care about it in all aspects of life. Our world is overly complicated by unnecessary and poorly expressed information and choices, and the problem is getting worse in our so-called age of Big Data. Throughout history great thinkers have campaigned for simplicity. Steve Jobs was fond of quoting Leonardo da Vinci: “Simplicity is the ultimate sophistication.” Never has the need for such a campaign been greater than today.

A new book, Simple: Conquering the Crisis of Complexity, by Alan Siegal and Irene Etzkorn, lives up to its title by providing a simple overview of the need for simplicity, examples of simplifications that have already enriched our lives (e.g., the 1040EZ single-page tax form that the authors worked with the IRS to design), and suggestions for what we can all do to simplify the world. This is a wonderful book, filled with information that’s desperately needed.

Too late for Christmas but I have a birthday coming up. 😉

Sounds like a great read and a lesson to be repeated often.

Complex documentation and standards only increase the cost of using software or implementing standards.

Whose interest is advanced by that?

Improving User Experience in Manuals

Wednesday, February 6th, 2013

Improving User Experience in Manuals by Anastasios Karafillis.

From the post:

The manual: possibly the most awkward part of a user’s experience with a product. People avoid manuals whenever possible and designers try to build interfaces that need not rely on them. And yet, users and designers would certainly agree that you simply must provide a proper manual.

The manual can be a powerful tool for unleashing the full potential of an application, something of benefit to users and vendors. Why is it, then, that manuals so often seem to confuse users rather than help them?

Let’s look at the most common difficulties faced by technical writers, and how to best deal with them to improve the user experience of manuals.

“…a proper manual.” Doesn’t seem to be a lot to ask for.

I have seen some better than others but they were all fixed compromises of one sort of another.

Ironic because SGML and then XML advocates have been promising users dynamic content for years. Content that could adopt to circumstances and users.

Instead we gave them dead SGML/XML trees.

What if you had a manual that improved along with you?

A manual composed of different levels of information, which can be chosen by the user or adapted based on your performance with internal tests.

A beginning sysadmin isn’t going to be confronted with a chapter on diagnosing core dumps or long deprecated backup commands.

A topic map based manual could do that as well as integrate information from other resources.

Imagine a sysadmin manual with text imported from blogs, websites, lists, etc.

A manual that becomes a gateway to an entire area of knowledge.

That would be a great improvement in user experience with manuals!

Mathematical Writing

Wednesday, December 5th, 2012

Mathematical Writing by Don Knuth, Tracy Larrabee, and Paul M. Roberts.

From the course catalog:

CS 209. Mathematical Writing—Issues of technical writing and the effective presentation of mathematics and computer science. Preparation of theses, papers, books, and “literate” computer programs. A term paper on a topic of your choice; this paper may be used for credit in another course.

Stanford University, Fall, 1987.

An admixture of notes, citations, examples, and war stories by several legends in the world of CS.

While making a number of serious points about writing, the materials are also highly entertaining.

I first saw this in Christophe Lalanne’s A bag of tweets / November 2012.

10 Tips on Writing from David Ogilvy

Monday, December 3rd, 2012

10 Tips on Writing from David Ogilvy by Maria Popova.

From the post:

How is your new year’s resolution to read more and write better holding up? After tracing the fascinating story of the most influential writing style guide of all time and absorbing advice on writing from some of modern history’s most legendary writers, here comes some priceless and pricelessly uncompromising wisdom from a very different kind of cultural legend: iconic businessman and original “Mad Man” David Ogilvy. On September 7th, 1982, Ogilvy sent the following internal memo to all agency employees, titled “How to Write”:

The one where I fail is: Never write more than two pages on any subject.

And could use the storing emails overnight and re-editing the next day.

Which ones would benefit you the most?

Spundge

Saturday, December 1st, 2012

First look: Spundge is software to help journalists to manage real-time data streams by Andrew Phelps.

From the post:

“Spundge is a platform that’s built to take a journalist from information discovery and tracking all the way to publishing, regardless of whatever internal systems they have to contend with,” he told me.

A user creates notebooks to organize material (a scheme familiar to Evernote users). Inside a notebook, a user can add streams from multiple sources and activate filters to refine by keyword, time (past few minutes, last week), location, and language.

Spundge extracts links from those sources and displays headlines and summaries in a blog-style river. A user can choose to save individual items to the notebook or hide them from view, and Spundge’s algorithms begin to learn what kind of content to show more or less of. A user can also save clippings from around the web with a bookmarklet (another Evernote-like feature). If a notebook is public, the stream can be embedded in webpages, à la Storify. (Here’s an example of a notebook tracking the ONA 2012 conference.)

Looks interesting but I wonder about the monochrome view it presents the user?

That is some particular user makes their settings and until and unless they change those settings, the limits of the content they are shown is measured by that user.

As opposed to say a human curated source like the New York Times. (Give me human editors and the New York Times)

Or is the problem a lack of human curated data feeds?

Read this: Revising Prose

Friday, November 30th, 2012

Read this: Revising Prose by Jason Zimdars.

From the post:

There are plenty of books that will teach you to be a better writer, but I’ve never found one so immediately useful as Revising Prose by Richard A. Lanham. Following along as Lanham revises example upon example of real world writing is like exercise for your writing muscles.

My favorite takeaway is this tip for improving the rhythm and cadence of your writing. Many of us have learned to read text out loud as a method to reveal awkward transitions or generally dull passages, but you can also spot poor rhythm visually. A red flag for dull cadence is a run of sentences that are all of similar length. Try adding a carriage return after every sentence or phrase, the rhythm is evident:

This looks like an interesting and easy technique to use on your own as well as the prose of others.

The better a writer you become, the easier it will be for potential clients, colleagues and others to understand what you have written.

Modulo that if you go into “public service” as they say in the United States, being understood may put you at a disadvantage.

As with most advice, it could go either way. 😉

Calligra 2.6 Alpha Released [Entity/Association Recognition Writ Small?]

Wednesday, October 17th, 2012

Calligra 2.6 Alpha Released

The final version of Calligra 2.6 is due out in December of 2012. Too late to think about topic map features for that release.

But what about the release after that?

In 2.6 we will see:

Calligra Author is a new member of the growing Calligra application family. The application was announced just after the release of Calligra 2.5 with the following description:

The application will support a writer in the process of creating an eBook from concept to publication. We have two user categories in particular in mind:

  • Novelists who produce long texts with complicated plots involving many characters and scenes but with limited formatting.
  • Textbook authors who want to take advantage of the added possibilities in eBooks compared to paper-based textbooks.

Novelists and text book authors are prime candidates for topic maps, especially if integrated into a word processor.

Novelists track many relationships between people, places, things. What if entities were recognized and associations suggested, much like spell checking?

Not solving entity/association recognition writ large, but entity/association recognition writ small. Entity/association recognition for a single author.

Text book authors as well because they creating instructional maps of a field of study. Instructional maps that have to be updated with new information and references.

Separate indexes could be merged, to create meaningful indexes to entire series of works.

PS: In the interest of full disclosure, I am the editor of ODF, the default format for Calligra.

All Presentation Software is Broken

Thursday, May 17th, 2012

All Presentation Software is Broken by Ilya Grigorik.

From the post:

Whenever the point I’m trying to make lacks clarity, I often find myself trying to dress it up: fade in the points, slide in the chart, make prettier graphics. It is a great tell when you catch yourself doing it. Conversely, I have yet to see a presentation or a slide that could not have been made better by stripping the unnecessary visual dressing. Simple slides require hard work and a higher level of clarity and confidence from the presenter.

All presentation software is broken. Instead of helping you become a better speaker, we are competing on the depth of transition libraries, text effects, and 3D animations. Prezi takes the trophy. As far as I can tell, it is optimized for precisely one thing: generating nausea.

Next Presentation Platform: Browser

If you want your message to travel, then the browser is your (future) presentation platform of choice. No proprietary formats, no conversion nightmares, instant access from billions of devices, easy sharing, and more. Granted, the frameworks and the authoring tools are still lacking, but that is only a matter of time.

Unfortunately, we are off to a false start. Instead of trying to make the presenter more effective, we are too busy trying to replicate the arsenal of useless visual transitions with the HTML5, CSS3 and WebGL stacks. Spinning WebGL cubes and CSS transitions make for a fun technology demo but add zero value – someone, please, stop the insanity. We have web connectivity, ability to build interactive slides, and get realtime feedback and analytics from the audience. There is nothing to prove by imitating the broken features of PowerPoint and Keynote, let’s leverage the strengths of the web platform instead. (emphasis added)

Imagine that. Testing your slides. Sounds like testing software before it is released to paying customers.

Test your slides on a real audience before a conference or meeting with your board or important client. What a novel concept.

By “real audience” I mean someone other than yourself or one of your office mates.

When you are tempted to say, “they just don’t understand….,” substitute, “I didn’t explain …. well.” (Depends on whether you want to feel smart or be an effective communicator. Your call.)

Presentation software isn’t fixable.

Presenters on the other hand, maybe.

But you have to fix yourself, no one can do it for you.

Let us abolish page limits in scientific publications

Thursday, April 19th, 2012

Let us abolish page limits in scientific publications

Daniel Lemire writes:

As scientists, we are often subjected to strict page limits. These limits made sense when articles were printed on expensive paper. They are now obsolete.

On the contrary, page limits (or their digital equivalents) are more important in a digital setting than when articles appeared in print. (Research data, source code and the like should not be subject to limits but that is a different issue.)

Why?

Perhaps you have heard of the DRY principle:


Don’t

Repeat

Yourself

The hazards of repeating yourself inconsistency, change of one reference and not another, etc., are multiplied in prose writing.

Why?

At least in computer programming, if you otherwise follow good programming practices, some of your tests or even the compiler will catch repetition as a bug. Which can then be fixed. Repetition in prose lacks the advantage of a compiler to catch such errors.

Do you want to be known for “buggy” prose?

Moreover, good writing isn’t accidental. It is a matter of domain knowledge, hard work and practice. Write in a sloppy fashion and before too long, bad habits will creep into your “professional” writing.

Do you want to lose the ability to express yourself clearly?

Finally, your writing reflects your respect (or lack thereof) for readers. Your work is being read for possible use in publications or research. Why would you inflict poor writing on such readers?

To me personally, poor writing reflects a poor understanding of content. Is that how you want to be known?

tl;dr

Saturday, April 7th, 2012

tl;dr

John D. Cook writes:

The slang “tl;dr” stands for “too long; didn’t read.” The context is often either a bad joke or a shallow understanding.

What bothers me most about tl;dr is the mindset it implies, scanning everything but reading nothing. I find myself slipping into that mode sometimes. Skimming is a vital skill, but it can become so habitual that it crowds out reflective reading.

I despaired when I read in the comments that someone used this as their entire review of an ebook version of “Moby Dick.” I have read it more than once and didn’t really notice the length, other than to be disappointed with I reached the end.

On the other hand, I have read short conference proposals that required me to force myself to the end of a three page abstract. Being uncertain at the end if the authors actually had a point or were trying to conceal some point.

Reflexive reading isn’t encouraged by some user documentation, which is written carelessly, inconsistently and apparently for the purpose of claiming it exists.

To avoid seeing the use of “tl;dr” on your work, convey some of your excitement about it by caring enough to write well. Readers will recognize your writing as a cut above the average and may consider that as a good sign about your software.

Best Written Paper

Saturday, March 24th, 2012

Best Written Paper by Michael Mitzenmacher.

From the post:

Daniel Lemire pointed to an article on bad writing in science (here if you care to see, not CS-specific), which got me to thinking: do we (in whatever subcommunity you think of yourself being in) value good writing? Should we?

One question is what qualifies as good writing in science. I’m not sure there’s any consensus here — although that’s true for writing more generally as well. While colorful word choice and usage can garner some attention* (and, generally, wouldn’t hurt), unlike what some people may think, good writing in science is not a vocabulary exercise. I find that two key features cover most of what I mean by good writing:

  1. Be clear.
  2. Tell a story.

Those two points cover “good writing” for all types of writing.

A Coder Interview With John D. Cook

Thursday, March 1st, 2012

A Coder Interview With John D. Cook

I have cited John D. Cook’s blog more than once.

I must confess that I cited this interview for the following quote:

What advice would you offer to an up-and-coming programmer?

Learn to express yourself clearly in writing. Buy a copy of Strunk and White and read it once a year.

If you’re a genius programmer but you cannot or will not write English prose, your influence will be limited.