Published
Monday, March 14, 2016 - 13:54
Written by

Hi! My name is Christian Maltais. I'm a founding member of Praxis Labs Coop. We recently launched a Civi hosting service with automated updates. However, I also wanted to help the community on a more personal level. Since I'm not a developer, I felt unsure. How could I fit in?

Luckily, the Civi folks are very welcoming, and the project needs all sorts of skills. I studied litterature in college, and I'm a pretty good copy editor. Turns out the "Features" section on civicrm.org needed some editing. That felt just right for me, so I got on it.

Editing is like thinning and weeding your garden. You're moving or removing what gets in the way; identifying and fixing potential problems.

Online readers have notoriously low patience. That's your biggest problem.

You can't make the readers more patient. You can however remove the things that try their patience, so that should always be your main concern.

On civicrm.org, I started with the simple things. I removed all the typos I could find. I shortened some sentences. I removed superfluous adjectives.

Since the section isn't fully themed yet, some paragraphs weren't automatically separated by interline spacing. This made the pages look cluttered and hard to read, so I added some empty lines directly in the text.

I then noticed that there were some big discrepancies in presentation from one page to the next. There are a dozen Features pages, which were probably written by different people at different times. This is normal for a community-driven project, but everyone had done things their own way. The section felt haphazard. This needed to be fixed, so once again I started with the most obvious discrepancies, like making sure the lists looked the same on every page.

I eventually hit upon a bigger issue. Each Features page has a sub-features section, labeled simply "Features". On some pages, it's presented as a list. On others, as a couple of paragraphs.

I prefered the lists; the paragraphs took more concentration to read, and they could sometimes feel a little like marketing copy. But when I tried to change the paragraphs into lists, it didn't work. The paragraphs only talked about one, maybe two features; not enough for a list.

The content simply wasn't there. The only option was to scrap the paragraphs, and start from scratch. This meant research: finding all the relevant documentation, going over it while noting down everything that looks or sounds like a useful feature, then making sense of those notes and putting them in a logical order.

The CiviCRM handbook was a great start, but it's not enough; I've also had to use articles and videos. Right now, I'm watching an excellent presentation by Jamie Novick on Youtube about the accounting features.

As you can guess, I'm still working on those lists.

I've provided you a few details on the work I've done so far because they help illustrate some useful editing guidelines:

1. Check grammar, spelling and punctuation
2. Keep presentation consistent
3. Keep things simple
4. Organize ideas logically
5. Remove anything that feels forced
6. Apply simple composition techniques
7. Garnish

The first five are about making sure you don't lose your reader. The last two are about style. This means they're optional, but they can help make an average article really shine. I'll go over all these guidelines in more detail next time.

Until then, if you feel like helping (either with editing or anything else), just contact me. CiviCRM is really about community involvement; no matter your talents, there's a place for you.

Don't be shy!