AtD at the DC CiviCRM Meetup
Washington, DC is full of non-profit organizations, advocacy groups, and NGOs. Last night I had a chance to meet with a group of CiviCRM enthusiasts. CiviCRM is an open source tool to help non-profits manage their donors. My goal was to spread the AtD love and talk about how one could add grammar and spell checking to their installation.
The instructions to add AtD to CiviCRM are:
- Extract atd-ckeditor.tgz into civicrm/packages/ckeditor/plugins
- I just noticed, the slides are wrong, it has to go into the plugins directory
- Edit civicrm/packages/HTML/QuickForm/ckeditor.php and follow slide 23.
- Run the Open Source AtD Service (it’s RAM hungry)
- Edit civicrm/packages/ckeditor/plugins/atd-ckeditor/proxy.php to point to your AtD server.
As you can see, it requires some hacking but it is possible. The same process for adding AtD to an app like CiviCRM is also possible for other applications as well. AtD has front-end components for TinyMCE, jQuery, and CKEditor.
The slides are here:
Towards a More Usable AtD with Content Editable
Working on the web is quite exciting. Standards are evolving and the ideal ways of doing things keep coming closer to reality. Proofreading text areas with AtD isn’t as natural as I’d like. Clicking a button activates a proofreading mode. This mode places the contents of the text area into a DIV and inserts the After the Deadline markup with the text. Under this model, you click the highlighted errors to select a suggestion from a context menu. Once you’re done proofreading your text area is restored with the updated contents.
This model works OK. GMail uses it. Meetup.com uses it. I believe I’ve seen it in many other places.
Last night I decided to play with the new contentEditable attribute. This new(ish) attribute allows a developer to flag an HTML element as editable. This means the user can interact with the contents of the element in place. They can type text, move the cursor, and anything else they would do with a text area. It’s exciting stuff. Up until now web apps have achieved in-place editing by creating an iframe displaying a blank page with the design mode attribute set to true. This solution is a bit heavy.
I’m looking at using contentEditable with After the Deadline. I’m almost surprised we haven’t seen it in more places. It’s a harmless attribute to add to an application. If it works, users can interact with the div as if it’s the text area until the text area is restored. If it doesn’t work, then the user is stuck interacting with the div using the conceptual edit and proofread modes.
The only challenge is dealing with newlines correctly. When you press enter, the browser creates a line-break or a new paragraph (this is unspecified). When emulating a text area this is undesirable. So I either get to make the proofread mode swallow enter key presses or emulate text editing behavior by detecting which browser is in use and taking browser specific action to insert a newline at the cursor. I shouldn’t have to do this as my div’s set the CSS attribute white-space to pre-wrap. Under this mode a newline in a div will produce a line-break. It’d be nice if the contentEditable mode honored this.
Despite this small hang up, contentEditable is an exciting change and we look forward to bringing it to a proofreading plugin near you.
WordCamp NYC Ignite: After the Deadline
I see that the After the Deadline demonstration for WordCamp NYC has been posted. This short five-minute demonstration covers the plugin and its features.
Before you watch this video, can you find the error in each of these text snippets?
There is a part of me that believes that if I think about these issues, if I put myself through the emotional ringer, I somehow develop an immunity for my own family. Does writing a book about bullying protect your children from being bullied? No. I realize that this kind of thinking is completely ridiculous.’’
[Op-Ed] … Roberts marshaled a crusader’s zeal in his efforts to role back the civil rights gains of the 1960s and ’70s — everything from voting rights to women’s rights.
The success of Hong Kong residents in halting the internal security legislation in 2004, however, had an indirect affect on allowing the vigil here to grow to the huge size it was this year.
These examples come from the After Deadline blog, When Spell-Check Can’t Help. You can watch the video to learn how After the Deadline can help and what the errors are. You can also try these out at http://www.polishmywriting.com.
You can also view the WCNYC session on how embed After the Deadline into an application.
George Orwell and After the Deadline
Ok, I have to admit something. George Orwell does not use After the Deadline. But, if he were alive now, I bet he would.
In his essay, Politics and the English Language, George Orwell defines the following rules for clear writing:
- Never use a metaphor, simile, or other figure of speech which you are used to seeing in print.
- Never use a long word where a short one will do.
- If it is possible to cut a word out, always cut it out.
- Never use the passive where you can use the active.
- Never use a foreign phrase, a scientific word, or a jargon word if you can think of an everyday English equivalent.
- Break any of these rules sooner than say anything outright barbarous.
Did you know After the Deadline can help you with these rules? Here is how:
Rule 1: Avoid clichés
You should avoid clichés in your writing. After the Deadline flags over 650 worn out phrases. These phrases lose their power because we’re so used to seeing them.
Rule 2: Use Simple Words
After the Deadline helps you replace complex expressions with simple everyday words. Examples include use instead of utilize, set up over establish, and equal over equivalent.
Rule 3: Avoid Redundant Expressions
A common poor writing habit is using phrases with extra words that add nothing to the meaning. After the Deadline flags these so you can remove them. Examples include destroy over totally destroy, now instead of right now, and written over written down.
Rule 4: Avoid Passive Voice
Like a good copy editor, After the Deadline uses its virtual pen to find passive voice and bring it to your attention. It’s up to you if you want to revise it or not. In most cases you will make your writing much clearer.
Rule 5: Avoid Jargon
This is a hard one as each field has its own jargon. After the Deadline flags some foreign phrases and jargon words. It’s up to you to try to find the right words depending on your audience.
Rule 6: Remember, rules are meant to be broken
Rules are great but they do not cover every situation. To help, After the Deadline uses a statistical language model to filter poor suggestions.
This is a repost from the old-AtD blog. If this topic interests you visit http://www.afterthedeadline.com where you can download After the Deadline for WordPress or learn how to add it to an application.
After the Deadline @ Washington, DC PHP Meeting
Last night I had the priviledge to present After the Deadline to the Washington DC PHP Meeting. Definitely one of the best audiences I’ve experienced. Thanks guys.
In this talk I demoed After the Deadline, talked about some of the NLP and AI technology under the hood, and showed how to embed AtD into an application using jQuery and TinyMCE.
Shaun Farrell was technically savvy enough to record it (I tried but my attempt failed). You can see the video here:
And the slides from the presentation are here:
If you’re looking at all this and thinking: “wow, this After the Deadline stuff is fun. I want to attend an After the Deadline live seminar in my area” then you’ve come to the right place. I’m demoing After the Deadline tonight at the Washington DC Technology Meetup in Ellicot City, MD and next week I’m giving a similar talk at the Baltimore PHP Meetup.
I’m tracking AtD related events on the Events page of this blog. If you’d like a speaker for your event, I’m glad to take this show on the road in the mid-atlantic region. Feel free to contact me raffi at automattic dot com.
Comments Off on After the Deadline @ Washington, DC PHP Meeting
AtD on WordPress Weekly Podcast
Last night I was interviewed by Jeff at the WordPress weekly podcast. If you listen, you’ll learn:
- What life is like at Automattic
- How AtD works
- Who a hit was ordered on and why
Comments Off on AtD on WordPress Weekly Podcast
The Ten People You Meet at WordCamp NYC
Now that WordCamp NYC is over, it’s time to show some link love to those I met. Thanks for saying hi to the smiling guy in the velvet blazer.
- I watched Jake Goldman‘s demo on the Recommended Reading using Google Reader Sharing Plugin for WordPress. I like this plugin because it follows the philosophy of do one thing, do it well, and make it easy to use it in different ways. There are many possibilities to populate your blog with content from your Google Reader feed consumption process with this tool. Great work.
- I met Carl Valcarcel yesterday at the beginning of a session. He blogs about genetic algorithms, eclipse plugins, and code.
- I ran into Chris Masiello at a Starbucks. I was talking about this blog post in fact. He wowed me with a neat story. He started as a pre-school teacher in the projects, moved to working IT so he could afford to eat, and then transitioned to a career as a technical trainer. He now blogs about how to use different technologies that he is passionate about, including WordPress.
- Jeff Chandler of WP Tavern fame was a presence to reckon with. We met at a discussion about open source communities led by Paul Kim. He was very up on what is going on and had a lot of great insights.
- I helped WCNYC volunteer Kitty Bradshaw put After the Deadline on her blog. It’s really neat to see the passion and diverse interests in the WordPress community. If you’re interested in NYC life from a California girls perspective, you’ll need to check her blog out.
- I ran into the Mojofiti guys at the speakers party. They’re doing neat stuff. They’ve joined WordPress-MU, BuddyPress, and Google’s Translation API to create a community website where all the content is automatically translated to your language as you read it. They’re trying to help the sharing of ideas by breaking down language barriers. Bravo guys.
- Another one I met from the speakers party was Stephanie Cockerl who is a NYC based blog developer and consultant. Stephanie gave a talk on WordPress analytics.
- I had the pleasure of eating lunch with Cris Lombardi and Elizabeth Willse. A journalist and a connoisseur of blogs and beers makes for an interesting time. Cris has a great passion and respect for the military and what soldiers, airmen, seamen, and marines go through. I appreciate her taking the time to spread our stories.
- Keith Casey made a visit to the AtD API session. He’s CTO of a technology company and blogs about open source and technology leadership. I’m definitely going to give his stuff a deeper read when I get a chance.
- Christine Labate, the Design Director of Designs for Growth, gets points for best networker. I love watching people and how they interact. Every time I saw Christine she was engaged in deep conversation with someone new. This is great and it’s the total power of conferences. A technology conference is going to have the whole range of values on the introvert to extrovert scale. Someone like Christine helps seed the process by bouncing around from group to group getting folks to open up.
- Anne Jonas, an AmeriCorps volunteer with the Participatory Culture Foundation was also in attendance. I think it’s so cool AmeriCorps is involved with IT infrastructure, community development, and helping organizations becoming self-sustaining.
- Danilo Diaz, Developer Evangelist, from Microsoft was a strong presence at the WordCamp. He gave a great talk on Windows Live Writer. Microsoft is embracing cloud computing and I look forward to Office Web Apps. I’m told document fidelity is their first priority but I’d love to see their proofreading tools brought to the web too. If they raise the expectations in this space, I expect others will look for solutions to meet that demand and AtD will be there to help 🙂 Selfish? I don’t know–I just want to help people write better.
So that’s my wrap up of the folks I met at the conference. Well, ten 12 of them anyways. Who did you meet?
WordCamp NYC – AtD Wrap Up
So today is day two of WordCamp. This was my first one and I have to say it was definitely a good time. I learned a lot, got to interact with many WordPress “personalities”, and showed off AtD a bit.
I gave two presentations. At yesterday’s 2:30pm session I showed After the Deadline and its features to a packed room. To those of you who made it as far as this blog, good to see you, I hope you stick around.
I also gave a talk at 10pm showing how to add After the Deadline to a web application using jQuery. Those present seemed like a strong jQuery crowd so this was a positive thing. I hope some of you try it out. For those who couldn’t make it (but wanted to) here is the presentation:
As a side note: I just noticed AtD corrects wordcamp to WordCamp. I’m on the ball for you guys 🙂
Re: Writing Great Technical Documentation
Jacob Kaplan-Moss has a great series on his blog about writing technical documentation. You can imagine this is a topic near and dear to my heart. He starts his series discussing what to write, technical details of writing, and continues it with a post about needing an editor.
His advice is great, but despite this I feel proofreading software was wrongly omitted from the discussion. The ideas are sound but instructing readers to look to the Chicago Manual of Style for specifics isn’t helpful. This creates a high entry barrier for those who want to improve their writing.
On technical style Jacob talks about many good principles that are popular in Plain English. He says to write short paragraphs, keep a conversational tone, omit fluff, and watch out for the passive voice.
One commenter mentioned that beating up on passive voice and telling writers to omit fluff is useless advice on its own. From a blog post how is the reader supposed to know what is considered fluff?
For these problems there are software style checkers. A style checker is (usually) a rule-based tool that looks for phrases editors get nit-picky about. It’s not the same as having a human editor but checking your writing against thousands of common pitfalls doesn’t hurt. In the UNIX world we’ve had GNU Style and Diction for many years. You can also use After the Deadline. For omitting fluff it finds complex expressions, redundant phrases, and clichés. For most things it flags it offers a usable alternative. For example, used is suggested for utilized.
There is nothing wrong with passive voice on its own. Use passive voice to downplay the actor who performed the action. The danger with passive voice is overusing it. Again, a style checking tool can flag your passive voice. If you see it in every sentence, you have a problem. If it’s a rare occurrence, no big deal.
The last post in the series talks about the need for an editor. Jacob’s first tip: don’t edit without permission. I have mixed feelings on this. I get edits in my email with a respectful tone, this is fine. And then I get those with a smug twist and that bothers me. The key is to be respectful. If you want to invite edits to your blog, consider a tool like GooseGrade. It’s a widget that invites your readers to notify you of typos and their relevant correction. GooseGrade has an interface that lets you accept these changes into your post with the push of a button.
I like Jacob’s tips about printing your document and editing it with a red pen. I do this when I’m editing an article and feel the extra attention to detail is worth the time. I also recommend reading backwards through the document. That helps me.
Jacob has a few typos in his third post. ‘You’ll be less likely to “know” that you got something write,’ is called out in the first comment. When I am tired, I mix up write and right. I do this all the time. We can’t expect a human editor for everything we write, but a mechanical check is always possible.
Spell checkers have a bad rap because most only flag an error if what you wrote happens to be missing from the dictionary. Fortunately these tools are evolving. The newest ones look at context and use statistics to detect misused words like right and write. After the Deadline has this feature.
The principles Jake discusses are good to know and readers will benefit. For the low-level details of some of these, there are software tools that can help you. As you’re writing documentation, I urge you to find a tool that works for you and add it to your process.
After the Deadline is an open source proofreading tool that checks spelling, style, and grammar. If you’re a developer you can embed it into your application. Plugins for jQuery and TinyMCE are available. You can try After the Deadline at http://www.polishmywriting.com
How to write a great blog comment (hint: spell check!)
I pay so much attention to what I write in my blog posts, trying to make the content balanced, and get the presentation correct. People judge me on my ability (or lack of) to write well. Comments also matter and today I found a post where one of my favorite writers, Grammar Girl, addresses this topic:
Quickly, here are Grammar Girl’s rules to write a great comment:
- Rule #1 — Determine Your Motivation — why are you writing the comment?
- Rule #2 — Provide Context — state what you’re responding to in the post or comments
- Rule #3 — Be Respectful — others may read what you write in the future, say only what you’d say to their face
- Rule #4 — Make a Point — “me too” posts are a waste of time, have substance
- Rule #5 — Know What You’re Talking About — speak with some authority or cite something useful
- Rule #6 — Make One Point per Comment — keep it focused and on track
- Rule #7 — Keep it Short — brevity is your friend, it’s a comment not the post
- Rule #8 – Link Carefully — you don’t want to come off as a spammer, people will call you on it
- Rule #9 — Proofread — people judge you on how you write!
And finally, my reason for writing this post in the first place:
Grammar Girl mentions readers should use a browser with a spellchecker to help avoid the troll who jumps in with: “What do you know about chocolate storage, you can’t even spell ‘their.'” Of course no browser spell checker that I know of will help you if you misuse there or their. Another option is to expect users to copy and paste into a Word Processor or PolishMyWriting.com. I do this sometimes, but it’s time consuming.
If you run a blog and want to help your readers, you can install the Intense Debate comment system and enable the After the Deadline plugin for it. Then your readers will have access to a hyper-accurate spell checker, misused word detection, and grammar checking. I don’t have proof of it, but who knows, maybe well written comments will help raise the level of conversation on your site. Let me know!
After the Deadline 
Comments Off on AtD at the DC CiviCRM Meetup