Nonprofits Archives - Spinning Code

Salesforce Nonprofit and Education Scratch Orgs

During the recent Open Source Commons sprint in Chicago, I tried to create scratch orgs for nonprofit and education clouds. Despite having some of the best people in the market in the room, including two Salesforce Solution Engineers, two levels of their bosses, and of course Google, I couldn’t figure it out.

As a follow up to a conversation there, Larry Fontillas sent me links to the help docs that contain what I consider partial answers. While I’ve sent feedback to help improve those articles, I am posting my current solution to this challenge.

My Example Scratch Config

On Github I created a repo that contains two scratch org configuration files:

Each is my attempt to create a definition that works for the named cloud. If are new to scratch orgs, I suggest you start with the Trailhead Salesforce DX Quick Start. With a Devhub setup, and connected to your sf cli, you can easily create these scratch orgs from my settings with one of the two following commands:

sf org create scratch -d -f config/nonprofit-cloud.json -a npc-org

sf org create scratch -d -f config/education-cloud.json -a edu-org

Industry Org Scratch Config Breakdown

The two new clouds leve re-usable components Salesforce built, licenses, and deploys across different markets. Salesforce does not currently provide one master switch you must use. Instead you need to know what features to include and tell the Devhub which collection to enable.

That is done in two major parts of the configuration file. In my Nonprofit cloud config file there are several sections, but two are critical: features and settings → IndustriesSettings. The features list includes Salesforce components to enable. In this case I included the nonprofit specific Fundraising, Program Management, and Grantmaking modules, but also OminiStudio, Accounting Subledger, and more because they included with NP Cloud by default. Under Industries Settings you’ll also see I enable Grantmaking and support for Program Management.

The Education Cloud config file has even more detail. That’s because Salesforce as made more available for Education Cloud. The Industries settings section includes more flags as well for the same reason. As I Followed the setup guide for Education Cloud, I further adjusted some of the base-line object permissions.

Here are the features I know you need to include for each cloud:

Feature	NP Cloud	Edu Cloud	Notes
AccountingSubledgerGrowthEdition	Optional	Optional	Starter Edition is also available
AccountSubledgerUser	Optional	Optional
AnalyticsQueryService	Yes	Optional	This is listed in the docs under Fundraising, but I have not yet found a direct description.
Assessments	Yes	Yes
EducationCloud	No	Yes (requires a quantity parameter)	Main Education Cloud objects, but only a sliver of the features.
EnableSetPasswordInApi	Yes	Yes	Allows the cli to set the password, you always want this.
Fundraising	Yes	Optional
Grantmaking	Yes	Optional (Rare)
IndustriesActionPlan	No	Yes
IndustriesSalesExcellenceAddOn	Yes	Yes	This is listed in the docs under Fundraising, but I have not yet found a direct description.
IndustriesServiceExcellenceAddOn	Yes	Yes	This is listed in the docs under Fundraising, but I have not yet found a direct description.
LightningScheduler	No	Yes	Lightning Scheduler gives you tools to simplify appointment scheduling in Salesforce.
LightningServiceConsole	Optional	Yes	Allows the Lightning Service Console and access features that help manage cases faster.
MarketingUser	Yes	Optional	Provides access to the Campaigns object.
OmniStudioDesigner	Yes	Yes	Listed in lots of samples, but I have not yet found a direct description. But clearly needed for OmniStudio.
OmniStudioRuntime	Yes	Yes	More for OmniStudio.
OutcomeManagement	Yes	No
PersonAccounts	Yes	Yes	We all love Person Accounts now! Technically this is optional, although the assumption is it your default.
ProgramManagement	Yes	No	Enables the NPC Program and Case management features.
PublicSectorAccess	No	Yes	Not entirely sure about this one, but some of the features for Education Cloud seem to leverage these objects and settings.

Feedback Please!

I have tested these configurations to the degree of seeing that they work as a basic level. But I have not, yet, used them for a serious project. I am confident other people will find details that are missing, or just wrong. Please file an issue on Github or leave me a comment here with suggested changes.

On Being An Activist

When someone tries to insult you with what you often see as a compliment it is worth stopping to reflect. Am I an activist? If I’m not, should I be?

On Valentines Day this year my wife and I spent a few hours at DSS for a meeting related to some of the children we work with in the Guardian ad Litem program. In the course of a rather tense conversation a caseworker tossed out “Well, I am not an activist.” with the clear intention of implying that I am, and that activists are a problem.

It is the first time I can recall being called an Activist as an insult, and I’ve been a bit hung up on the topic ever since.

Between my personal and professional life I have a very high standard for what it means to be an activist. I have friends, including a former boss, who were arrested the recently protesting the conditions asylum seekers face coming to the US. Among them my friend Lucy who is willing to do this for more than just one cause. I was around when AFSC started to help restore the legacy of Bayard Rustin and his work planning the March on Washington and making the phrase “Speak truth to power” commonly known. My friend Tom Fox traveled around the middle east participating in peace movements until he was kidnapped and murdered in Iraq.

Those are activists.

At AFSC I had colleagues who would argue if you haven’t been arrested for a cause you aren’t really an activist. We had critics who argued that because AFSC staff were paid they couldn’t be true activists. I didn’t then, nor now, fully agree with those arguments, but my point is that when someone calls me an “activist” those are the comparisons they are drawing in my mind.

My credentials as an activist on that scale are weak at best. The first time I spent a lot of time with activists was in 1999 during the Hague Appeal for Peace and a peace walk that followed. The group walked from the Peace Palace – home of the international criminal court – in The Hague, Netherlands to Nato Headquarters in Brussels, Belgium. That picture of the water cannon firing on a crowd at the top of the page is mine, although I wasn’t willing to risk arrest that day (my sister was getting married the next week and my mother would have killed me if I’d missed it because I had been arrested in Europe – would a true activist be deterred by such things?).

It was a great experience, but didn’t do a thing toward our goal of nuclear disarmament – I now live in a town supported by nuclear weapons maintenance (and soon pit production too).

After college I took a job at AFSC which consisted of largely back office functions of one type or another – while defining for my career and personally gratifying work there is an important difference between building the tools activists need to communicate and being the activist. In 2008 I was part of planning a peace conference in Philadelphia as part of the Peace and Concerns standing committee, but it is important to note that I objected to the civil disobedience that was part of that event (being a consensus driven process people feared I would block it entirely – but I stood aside so they could move forward).

I’ve been to other events and protests, although sometimes as much accidentally as purposefully. So while the account is not empty, it’s not exactly the kinda stuff that gets you into history books, or even an FBI file worth reading.

Having spent much of my professional life supporting back office functions on nonprofits, and now interacting with DSS as a volunteer who has to be careful about what I share since I have to maintain the privacy of the kids we work with, I struggle to envision myself as an activist. I support activists sure, but I don’t see myself as one.

But when someone tries to insult you with what you often see as a compliment it is worth stopping to reflect. Am I an activist? If I’m not, should I be?

It occurred to me this case worker has a much lower standard of what it means to be an activist than I do – anyone who simply speaks against the status quo in favor of well established laws and precedents are activists in his book. To be fair he’s not far off the suggestion Bayard Rustin, and the committee who helped him write Speak Truth to Power, were making. And as much as I am sure they would deny it, the caseworkers are the most powerful people in the lives of children in foster care: they dictate where the children live, who they can talk to, if/when they see siblings, when they buy clothes, where they go to school, what doctors they see, and without an active advocate they shape how the courts see the children. And right now in South Carolina their power is being tested and reigned in because a group of Guardians ad Litem stood up a few years ago to the rampant systemic abuses.

The ramifications of that class action are still being determined, and no one really knows what the lasting effect will be. But this case worker has inspired me to make sure we honor the sacrifices they made (all were forced to stop fighting for the named children because they were “distractions”).

I’m not sure I am an activist, but I promised those kids I would stay with them until the judge ordered me to stop. No matter what taunting I get from the case workers, their bosses, and others within the power structure I can speak truth to power as long as I must.

“I can’t think of a single reason why we’re here, except that we’re needed.”

My wife and I are fans of M*A*S*H. When B.J. first arrives in Korea Hawkeye takes him to Rosie’s Bar and tells him: “I can’t think of a single reason why we’re here, except that we’re needed.” Oddly I’ve found this to be true of a great many service opportunities in my life; often the most useful ways to serve my community seems to require doing a things that should be utterly unneeded.

Often it has been around medical care. A few years ago we had a friend who spent more than a year in long-term respiratory rehab. Her daughter wasn’t able to visit much, and so we started to go most weekends just to see her. Not only did her emotional state improve but because we started to leave markers of loving family (a handmade afghan, photos, window clings, and other similar things) her medical care improved. That these things made a difference to how the staff treated her shouldn’t be true. When our own family members are in the hospital we try to ensure they get as much visitation as possible for the same reason.

Most recently it’s been while supporting children in foster care.

My wife and I serve as volunteer Guardian ad Litems in South Carolina (other states call the program CASA). It means we are court appointed advocates for children in foster care. We are the only people in their lives tasked with being openly biased in their favor. In practice it means we go to lots of meetings with professionals who should be better trained than us, better resourced than we are, and try to make sure they do their jobs the way the law requires. All children in foster care in South Carolina have a right to a volunteer advocate because the professionals who used to be paid to do this work didn’t do it as well as volunteers – nothing about that should be a true statement, but in 2010 the South Carolina Supreme Court ruled it was and from everything we’ve seen it is. So instead of a lawyer, they get us.

With just a few hours of training, that covered lots of information but barely scratched the surface, we were cut loose to help kids fight to make their lives whole again – ideally even better than before. We became part of a system run by underpaid, under-trained, and overloaded professionals. We go to all the meetings that happen in the lives of these children. We go to school and their home(s); we talk to everyone who passes through their lives during their time in the system; we visit the juvenile detention center to meet with our kids and prisons to meet with mom or dad; talk to doctors, lawyers (ours, their parent’s, and DSS’s but the kids rarely get their own in family court), case workers, detectives, probation officers, teachers and principals, parents, grand parents, foster parents, aunts and uncles, neighbors, and anyone else in their lives. Everyone else on that list worries about their own interests (like the parents do), other people in the family (like the case workers are federally obligately to do), are narrowly focused on one aspect of the child’s life (like their doctors are), or have worry about too many other people whose interests may conflict (like teachers must). My wife and I make sure we talk to more people than anyone else on the case, so that we can we represent the child’s interests and desires clearly and accurately.

We work with teenagers who have had all control of their lives taken away as they need to be learning to take more responsibility for their actions. The system is not designed well for the needs of teenagers, and so it falls to us to start helping these young people start to regain at least a little control of their destiny. The law requires us to meet with them once a month, but often it is more frequent (particularly with those prone to getting into trouble), and we become the only people they have who are both honest and unfailingly supportive. We are also too often the only people listening to their opinions about what’s happened and what they want to have happen next.

Our only real power, beyond being allowed into meetings, is that we are required to make recommendations to the court about what should happen. The court can ignore us, although they do so far less than people tell us to expect and the judges always listen with interest to to what we say. The vast majority of our impact happens outside of the court room, when professionals work harder just because they know we are watching.

Being a GAL is equal parts wonderful and infuriating, but at all times useful. We have discovered that just having a totally biased volunteer in the child’s life often makes the professionals more responsive to the child’s needs. Our schools are deeply under-resourced, and frequently seek to avoid providing legally mandated but expensive services so my wife is becoming an expert in education law to allow her to ensure the children’s rights are respected. But she has found that once she meets with the school administrators once or twice, and see that someone believes the kid is worth fighting for, they join us and help ensure the child is getting the support they need. Group homes, even terrible ones that openly allow their staff to beat children in ways that are banned for our prison guards (there is a true story behind that), are more careful when they know a volunteer is watching over a specific child and holding them legally accountable.

Sometimes just having a person around who cares, and thinks someone else is worth caring about, helps people who should do their jobs regardless of what’s happening, do their jobs better.

Preparing for your next crisis

Can your plan handle the bizarre?

Last winter Dries, the Drupal Association, and the whole Drupal community, stumbled when concerns about a leading contributor’s potentially exploitive relationship got caught up in discussions of Gorean subculture and related sexual behaviors (warning researching this topic will quickly lead you to NSFW information). The intriguing details drew in an ever-expanding audience but were actually irrelevant the main concerns and the secondary ones that followed. The DA lost control of the message and the story and the entire community suffered as a consequence. Last spring and summer I was asked to step in to help them regain control of the message and start to resolve the crisis. It wasn’t the first time I was part of a crisis response with unusual details, and likely won’t be the last.

The first time I saw an organization respond to a threat to their reputation was my senior year at Hamilton College when I was intern in the Communications and Development Department. The morning of February 5th, 2001 the administrative assistant who spent every Monday morning scanning major publications for references to the college and its professors (this is before you could use Google Alerts and other tools for a similar purpose) suddenly jumped up from her desk and ran into her boss’s office. A few moments later they both sprinted down the hall to the Vice President’s office. She had found an article in the New York Times Magazine titled The Cloning Mission; A Desire to Duplicate featuring then-chemistry professor Brigitte Boisselier who – unbeknownst to the college – was moonlighting as the research director for Clonaid trying to develop human cloning technology as part of her leadership of Raëlianism.

Yup, the first time I had a front row seat to an organization’s crisis was a college learning from the New York Times that they had a professor doing secret human cloning research for a group that believes aliens created humanity.

Within a hour they had a preliminary message prepared for any alumni who called – and they were calling – and got it to all alumni class presidents to share with any concerned classmates. By noon they had held meetings with all the needed decision makers including the college president, the chemistry department chair, the deans, and the VP of Communications to form a plan of action. By early afternoon that turned into a more formal statement that was recirculated to the class presidents and anyone else expressing concern to the school. Over the course of the semester, and the two years that followed (she continued to make world news after she left the college), they responded to repeated media inquires – I was one of several interns in a mock audience for b-roll footage of a CBC piece on the topic – and even got her to engage in a public debate with an ethicist from the Philosophy department (which went poorly for her). In the end the concerned alumni were pleased with the college’s handling of the matter and the school’s reputation remained intact.

Eventually every organization will face a crisis that requires a public response. Depending on the nature of your organization you may already have a plan that handles the obvious situations: like schools preparing for threats to their students or political campaigns preparing for sexual harassment claims (at least they all should be prepared regardless of what their candidate tells them). But in my experience most of the time the crisis that actually emerges isn’t what you expected and includes strange details that easily distract everyone from the main issue.

Hamilton did not have a plan titled: “What happens if one of our professors is caught leading human cloning research for an alien cult.” What they had was a general plan for “What happens when it appears someone is going to make us look bad” that was quickly escalated to “what happens when it really is bad.” They knew who they needed to get into a meeting, and that allowed timely decision making. The communications team then had a basis to work quickly so they could get back in control of the story. The plan they had allowed them to brush aside the unimportant details – the involvement of Raëlianism was fun to talk about but didn’t change anything about the response – so they could focus on important details.

Often when faced with these kinds of strange details surrounding a crisis the people who should be leading the response get distracted and start talking about those details. When it gets really weird they really want to say “is this not my fault and not my problem” and ignore it. It doesn’t matter why just that it is your problem. Everyone will want to focus on the salacious details, but you have to focus on the important details and lead your audience to supporting your response.

These are my tips for how to plan for a crisis and building a response that allows you to stay focused:

Know when to initiate your response. Develop a list of people and metrics to use to initiate a crisis response. It should include both some clear markers – e.g. a threat of violence against staff or constituents – and some fuzzier signs – e.g. anytime the ED/CEO or board chair says there is a crisis.
Know who needs to be involved and how to find them. Part of what allowed Hamilton to move quickly was they knew exactly who needed to be involved in the process. Likewise you should determine which staff, board members, volunteers, consultants, etc, need to be in the loop and how you reach them quickly. And know who gets cut out when – if your board chair is on a cruise and can’t be reached until next Tuesday who do you call instead? If your director of communications is the problem you’re probably better off not having them planning the response.
Prepare different types of response. You may want to monitor the situation while saying nothing; you may want to target different messages to specific audiences (your board may get a different message than your donors); you may want to try to use press contacts or avoid them. You should think about how and when to use all your communications channels as part of your response.
Have metrics for testing your plan before following it. In a time of stress it can be easy to overlook important details in your response. While planning write up a checklist to run through to make sure you remembered everything that’s important. It should at least include a reminder to think about everyone’s physical safety and your legal risk (in that order). It should also probably include contacts with important constituent groups (like Hamilton’s alumni class presidents) and any internal audiences so staff and volunteers aren’t surprised by public statements.
Be prepared to share aggressively. Often organizations appear to be hiding information when they share it slowly, or when they say “this is all we can release” and then are pressured into releasing more. With any given statement release everything you can – sometimes with supporting materials if you need to – and then stop.
Be prepared to shut up. This correlates with the previous tip. Sometimes part of a good response will be to be quiet. Usually this will be right before and after a major statement. It gives people a chance to process your response and avoids the sense that you are leaking information in dribs and drabs.
Don’t over plan. Your next crisis will not look like what you planned for, so be prepared to change course from your very first move. If you lock in to many details you will likely make your situation worse by sounding tone-def.

When you have created your draft plan you should practice using it. Some of that practice should be very practical: what do you do when a man in leadership is accused of sexual harassment or abuse? Some of it should be like the CDC and FEMA zombie drills; even if you don’t use zombies use a crisis that you think couldn’t possibly happen – if you hear someone in the office say “good thing that can’t happen here” use it as your scenario. The first makes sure you are prepared for the kinds of things that are most likely to actually happen. The second makes sure you are prepared to think outside the box and handle a messy situation to which you thought you were immune. Your organization might not do any medical research at all, but what would happen if you discovered a board member was marrying the next director of Clonaid (including aliens is almost as fun as including zombies)? What would you tell your major donors?

A good crisis response comes from being prepared for the unexpected. If your plan is flexible enough to handle the utterly expected and adapt to a staff member cloning alien zombies, you can probably handle whatever actually comes your way.

Make sure you have the pictures your site requires

One of the challenges that organizations of all shapes and sizes frequently face is getting good pictures to go with their web site design. Good images can draw in your audience but a missing or poorly displayed image risks damaging your credibility.

Frequently organizations fall in love with a site design that includes excellent pictures on every page. Each story in the design has a wonderful supporting image to highlight a person, place, or topic. Landing pages may have main images with carefully placed text and overlays to help draw the eye and keep people’s attention. Those designs and images may be great, but only if you provide new images as fast as you create new pages (often faster).

Much of the time I worked for AFSC we were lucky to have an in-house photographer. Terry Foss traveled around the world to visit, get to know, and photograph AFSC’s programs and he provided us with excellent pictures for nearly every area of our work. But even then we still had challenges getting the exact picture we wanted for the story we needed to tell the moment we wanted to tell it. In addition to his wonderful images we would dig in the archives, beg local program staff to send us more images, and sometimes we end up taking a picture of an intern’s hand or other acts of desperation.

Web designers have to make many assumptions when they design a site and one of the most important practical issues is the quality and quantity of art the client can provide. The more prominent and plentiful the image use, the more specific questions have to get; sometimes down to the level of aspect ratios and staff image editing skill level. Good designers use this information to help make sure the images in their designs are the kinds of images you can routinely provide. You should know what those assumptions are and make sure you can follow through over time.

When you first launch a site this isn’t usually a problem. A lot of time will go into the stories and images that are included during the build and migration so the initially launched site should be at least as wonderful as the designs.

But as time passes the constant need to specific kinds of images may become a burden. You will soon realize there are places that images are required for technical or stylistic reasons. Some images will have text overlays that mean the subject needs to be on the right or the left. Some spaces will be very large or very small, which impacts what subjects work well. Some will be surrounded by a background color or pattern that may clash with an otherwise ideal photograph. The more you understand this while working with your designer the more you’ll love your new site.

Hand holding a pen — Here’s that image from the Wayback Machine. The image is owned by AFSC and was published under a creative commons license.

We had to photograph an intern’s hand because at the time our home page would break if every story didn’t have an image – it was a design and technical requirement. A few months after we launched we needed to post a statement that required home page placement, but the statement had no image to go with it. I had no budget to buy a stock image and the program had no appropriate picture we could use, so one of our team members grabbed his camera and an intern and quickly shot a few pictures of the young man’s hand holding a pen. We ended up using that hand image for several statements after that as well.

So here are a few quick guidelines for making sure your web site isn’t held back by a need for art you can’t consistently provide:

Make sure you have a plan for getting new pictures. There are many ways to do this so having a plan is more important that its details. It can be a staff photographer, freelance photographers, volunteer photographers, an organization owned camera that staff use, or a budget for stock photographs. The best plans are usually some combination of all these pieces.
Talk with the site designer and make sure they know what you are able to provide before they start the design. Will you be able to ensure pictures for every story, blog post, and event? Do you have editorial standards about the use of images of program participants, volunteers, and staff? Does your stock image budget allow you to fill any gaps, or can you create a picture of an intern writing a statement from thin air? Can you edit those pictures to work in a variety of spaces and sizes, or do you need to assume the pictures get uploaded more or less they way they come off your camera?
When you start to see designs ask your web development partners lots of questions and document their answers. Ask about every image you see in the designs. For every single image you should know what size it needs to be, how it gets loaded and changed, if is required or optional (and how things look if it’s not present), and if it requires some kind of preprocessing for an overlay or other visual effect. Make sure you understand the purpose and details for every image they show you.
Try lots of variations when the site is still under development. Upload great images, terrible images, images that seem too big and too small, a sunset over a field, an ocean scene, a portrait of a baby, a team group shot, fluffy animals, flowers, and anything else you have around your computer. For each spot you can put a picture try each image and see what works and what doesn’t. No design can handle any image of any size and description equally well so make sure you understand, and can live with, the limits imposed by the design of your site.

Finally, make sure you actually follow the plan or fix it. Having a camera is only useful if someone is comfortable using it. Volunteers may not provide what you need in time to be useful or may forget to sign the releases your board requires. Budgets get cut or adjusted over time and may no longer really meet your needs. When the rubber meets the road your plan may not always work, don’t panic, just fix it. The reason you took all those notes about what you need is so that when you adjust your plan you will already know what it needs to provide to make your site successful.

Early Thoughts on Drupal Governance Change

One of the things that the Drupal community has learned in the last few weeks is that our current governance structures aren’t working in several ways. Having spent a lot of time at DrupalCon talking about these issues I figured I share a few initial thoughts for those working on our new processes.

This isn’t the first time I’ve been part of a community that was changing how it organizes itself. In my religious life I am a Quaker, and for a long time I was a member of Philadelphia Yearly Meeting which is the regional organizing body for Quakers in the greater Philadelphia area. And I served for a time on several of their leadership committees. I’ve seen that 300+ year old group pass through at least three different governance structures, and while many of the fundamentals are the same, the details that matter to people also change a lot.

My great aunt put it into perspective during one of the long discussions about change. When my wife asked her for her opinion about a then pending proposal she responded that it didn’t matter much to her as long as it worked for those willing to take leadership roles at the moment.

So as the Drupal community grows through a process to change our leadership structure here are the things I think it is important for all of us to remember.

It will not be perfect. We’re human, we will make mistakes, that’s okay.
It will change again. I don’t know when or why, but whatever we do will serve us for a time, and then we’ll replace it again.
Most of the community won’t care most of the time. Most of the time, most of us don’t notice what Dries, the Drupal Association, Community Working Group, and all the other groups that provide vision and leadership are doing.

I think we can all agree my first point is a given. I mention it mostly because some of us will find fault in anything done going forward. We should remember the people doing this work are doing the best they can and give them support to do it well.

On the plus side, whatever mistakes we make will be temporary because Drupal and its community will outlive whatever we create this time. We’ll outgrow it, get annoyed with the flaws, or just plain decide to change it again. Whatever we build needs to be designed to be changed, improved, and replaced in the future. Think about it like the clauses in the U.S. constitution designed to allow amends to the constitution itself.

Finally, we should remember that community and project governance is insider baseball. Understanding how and why we have the leadership we do is like watching a pitching duel on a rainy day, most baseball fans don’t enjoy those kinds of games. Most of our community wants to use Drupal and they don’t want to have to think about how DrupalCon, Drupal.org, and other other spaces and events are managed. That will not prevent them from complaining next time there are problems, but it is a fact of life those who do care should acknowledge.

Our community is stronger than we have been giving it credit for in the last few weeks. We need to be patient and kind with each other, and we’ll get through this and the divisions that will come in the future.

Documenting your work

Programming books — Your documentation does not need to look like this.

Early in my career I spent a lot of time as the only technical person on project, and therefore believed that I didn’t need to document my work carefully since I was the only person who had to understand it later. It turned out that if a project was back burnered for a few months the details were pushed out of my mind by the details of eight other projects.

Any project that takes more than a couple hours to complete involves too many details for most people to remember for more than a few days. We often think about project documentation as something for other people – and it is – but that other person may be you in six months.

I learned to start keeping notes that I could go back to, those notes would turn into documentation that I could share with other people as the need developed. My solutions were typically ad-hoc: freeform word documents or wiki pages. For a while I had a boss who wanted every piece of documentation created by IT to fit a very predictable format and to be in a very specific system. It took two years for him to settle on the system, process, and format to use. By then I had a mountain of information in wiki pages that documented the organization’s online tools in detail, and no one else is IT had anything substantial. It was two more years before the documentation of other team members got to be as good as my ad-hoc wiki.

That’s not to say a rogue solution is best, but the solution that I used was better than his proposed setup for at least three years. That experience got me to think about what makes documentation useful.

Rules of thumb for good project documentation:

Write up the notes you’d want from others when coming into a project: think of this as the Golden Rule of documentation. Think about what you’d want to have if you were coming into the project six months from now. You’d want an outline of the purpose of the project and the solution used, and places they deviated from any standards your team normally uses. You’ve probably read documents that are explaining something technical to an expert that are hard for anyone else to understand – if I’m reading the documentation I want to become an expert, but I’m probably not one already.
Keep it easy to create and edit while working: if you have to stop what you’re doing and write your notes in a totally different environment that your day-to-day work you will not do it. Wikis, markdown files, and other similar informal solutions are more likely to actually get written and updated than any formal setup that you can’t update while doing your main work.
Document as you go: we all plan to go back and write documentation later and almost none of us do. When we do get back to it, we’ve forgotten half the details we need to make the notes useful to others. So admit you’re not going to get back to it and don’t plan to: write as you go and edit as you need.
Make sure you can come in in the middle: People skim project documentation, technical specifications, and any other large block of text. Make sure if someone has skipped the previous three sections they can either pick up where they left off, or give them directions to the parts the need to understand before continuing.
Track all contributions: Use a system that automatically tracks changes so you you can see contributions from others and fix mistakes. Tools like MediaWiki, WordPress, and Drupal do this internally. Markdown or text files in a code repository also have this trait. Avoid solutions like MS Word’s track changes that are meant for editing a final document not tracking revisions over time.
Don’t fear editing: follow the Wikipedia community’s encouragement to Be Bold. You should not fear making changes to the team’s documentation. You will be wrong in some of what you write, and you should fix any mistake you find – yours or someone else’s. Don’t get mad if someone makes a change that’s not quite right, revert the change or make a new edit and more forward.
There is always an audience: even if you are the only person on the project you have an audience of at least your future-self. Even if it feels like a waste in the moment having documentation will help down the road.

Remember even if you are working alone you’re on a team that includes at least yourself today and yourself in the future. That future version of you probably won’t remember everything you know right now, and will get very annoyed at you if you don’t record what they need to know. And if the rest of your team members aren’t just versions of yourself they may expressed their frustration more directly.

Looking at a project from different angles

For our 15th anniversary my wife and went to the south island of New Zealand, with a long layover in Sydney. We only had a few hours in Sydney so we went to see the Opera House and then walk through the botanical gardens next door.

As we walked around the harbor I took pictures of the opera house from several different angles. And that got me thinking about the advice I’ve been given both about photography and about my work: make sure you try things from different angles.

Too often all kinds of experts get into a rut and lose track of the perspective non-experts, and other experts with whom they disagree. Cable news channels like to package those ruts as two talking heads yelling at each other by calling it “debate”.

It’s an easy trap to fall into even without watching the people paid to yell at each other. Sometimes when we look at a problem twice it looks different because we changed something small, and we think we’ve seen all the valid angles. But we’ve just reinforced our sense of superiority not actually explored anything interesting yet.

When you look right at the sun a small change can have a large impact, but you may still be fundamentally in the same place with a fundamentally flawed perspective.

And sometimes you look from a new angle and something easily recognizable becomes new and different, but that’s not always an improvement. There are reasons for best practices, and sometimes we just reinvent the wheel when we try to break our own path.

You don't see pictures of the opera house from this angle often – which is probably for the best. — You don’t see pictures of the opera house from this angle often – which is probably for the best.

This angle was even worse. It's a good thing I wasn't using film for this exercise. — This angle was even worse. It’s a good thing I wasn’t using film for this exercise.

And sometimes it is important to think about the extra details that you can capture by changing perspectives and taking the time to figure out the best approach.

Opera House with sailboat — I had to wait a few minutes for the sailboat to get into a spot that made it look right.

Sometimes too much context is too distracting. — Sometimes too much context is too distracting and makes it hard to know what you’re supposed to look at.

But when you take the time to look at things from different angles, perspectives, and positions sometimes you get to discover something you didn’t know to ask about.

This little guy and an older buddy spend lots of time in the sun on these steps behind the opera house – I had no idea they were there until we were walking around. — This little guy and an older buddy spend lots of time in the sun on these steps behind the opera house – they are well known locally, but I had no idea they were there until we were walking around.

For me the best moments are those gems you find when you take the time to explore ideas and view points and discover something totally new. Nothing beats travel to help you remember to change your perspective now and again.

Picking tools you’ll love: don’t make yourself hate it on day one.

Every few years organizations replace a major system or two: the web site, CMS, CRM, financial databases, grant software, HR system, etc. And too often organizations try to make the new tool behave just like the old tool, and as a result hate the new tool until they realize that they misconfigured it and then spend 5-10 years dealing with problems that could have been avoided. If you’re going to spend a lot of money overhauling a mission critical tool you should love it from day one.

No one can promise you success, but I promise if you take a brand new tool and try to force it to be just like the tool you are replacing you are going to be disappointed (at best). Salesforce is not CiviCRM, Drupal is not WordPress, Salsa is not Blackbaud. Remember you are replacing the tool for a reason, if everything about your current tool was perfect you wouldn’t be replacing it in the first place. So here are my steps for improving your chances of success:

List the main functions the tool needs to accomplish: This is the most obvious thing to do, but make sure your list only covers the things you need to do, not the ways you currently do it. Try to keep yourself at a relatively high level to avoid describing what you have now as the required system.
List the pros and cons of what you have: Every tool I’ve ever used had pluses and minuses. And most major internal systems have stakeholders who love and hate it – sometimes that’s the same person – make sure you capture both the good and bad to help you with your selection later.
Develop a list of tools that are well known in the field: Not just tools you know at the start of the project. Make sure you hunt for a few that are new to you. You might think you’ve heard of them all cause you walked around the vendor hall at NTC last year, but I promise you there are more companies that picked a different conference to push their wares, and there are open source tools you might have missed too.
Make sure every tool has a salesperson: Open Source tools can be overlooked because no one sells them to you, and that may mean you miss the perfect tool for your organization. So for open source even the playing field by having a salesperson, or champion, for the tool. This can be an internal person who likes learning new things, or an outside expert (usually paid but sometimes volunteer).
Let the sales teams sell, but don’t trust them: Let sales people run through their presentations, because you will learn something along the way. But at some point you also need to ask them questions that force them off your script. Force a demo of a non-contrived example, or of a feature they don’t show you the first time. Make them improvise and see what happens.
Talk to other users, and make sure you find one who is not happy: Sure your organization is unique but lots of other organizations have similar needs for the basic tools – unless you have a software-based mission you probably do not want an email system that’s totally different from everyone else’s. A good salesperson will have no trouble giving you a list of references of organizations who love the tool, but if you want the complete picture find someone who hates it. They might hate it for totally unfair reasons, but they will shed light on the rough edges you may encounter. Also make sure you ask the people who love it what problems they run into, remember nothing is perfect so everyone should have a complaint of some kind.
Develop a change strategy: In addition to a data migration plan you need to have a plan that covers introducing the new tool to your colleagues, training the users, communicating to leadership the risks and rewards of the new setup, and setting expectations about any disruptions the change over may cause. I’ve seen an organization spend nearly a half million dollars on customization of a complex toolset only to have the launch fail because they didn’t make sure the staff understood that the new tool would change their day-to-day tasks.
Develop a migration plan: Plan out the migration of all data, features, and functions as soon as you have your new tool selected. This is not the same thing as your change strategy, this is nuts and bolts of how things will work. Do not attempt to do this without an expert. You made yourself an expert in the field, but not of every in-and-out of the new system: hire someone who is. That could be a setup team from the company that makes it, a 3rd party consultant, or a new internal staff person who has experience with different instances of the tool.
Get staff trained on using the new tool: don’t scrimp on staff training. Make sure they have a chance to learn how to do the things they will actually be doing on a day-to-day basis. If you can afford to have customized training arranged I highly recommend it, if you cannot have an outside person do it, consider custom building a training for your low-level internal users yourself.
Develop a plan for ongoing improvement: you will not be 100% happy 100% of the time, and over time those problems will get worse as your needs shift. So make sure you are planning to consistently improve your setup. That can take many forms and what makes the most sense will vary from tool to tool and org to org, but it probably will mean a budget so ask for money from the start and build it into your ongoing budget for the project. Plan for constant improvement or you will find a growing list of pain points that push you to redo all this work sooner than expected.You’ll notice I never actually told you to make your choice. Once you’ve completed steps 1-6 you probably will see an obvious choice, of not: guess. You have a list, you listened to 20 boring sales presentations, you’ve read blogs posts, white papers, and ad materials. You now are an expert on the market and the tools. If you can’t make a good pick for your organization, no one else can either so push aside your imposter syndrome and go with your gut. Sure you could be wrong, but do the best you can and move forward. It’s usually better to make a choice than waffle indefinitely.

Nonprofits Drive Innovation in Online Communications

I spent ten years working at a nonprofit organization wishing I had the kinds of resources that large corporations can put toward their marketing efforts. A nonprofit the organization’s web site and related marketing are usually seen as overhead, and overhead is bad, therefore budgets limited. Nonprofit budgets are tight in general which doesn’t leave a lot of extra room for fancy services, tools, and consultants.

Then I started to work with large corporations. Turns out, all that money doesn’t necessarily bring you people who know how to spend it well. Yes the margins are bigger, and there is less complaining about the basic costs of doing business, but when it comes right down to it they aren’t any more strategic than a small scrappy team of people in the communications department of any organization large enough to have a communications team.

This shouldn’t have been a surprise. A great deal has been written about start-up culture and ways to help companies recreate the energy, passion, and creativity of their lean early days. And there has been a great deal written about impostor syndrome which nonprofit communications staff tend to have in spades.

Of course I’m speaking here in sweeping generalities about two massive groups, but here is what I’ve seen working with both nonprofits and for-profits:

As a group nonprofit staff are there because they care about the cause(s) of the organization, and they are driven to help the organization succeed despite their lack of resources.
The lack of resources — both in terms of time and money — forces NPOs to find creative solutions to their problems. They moved aggressively into social media because it was a free way to spread their message: companies then used the lessons learned by nonprofits to craft their early engagements with social media.
Due to corporate donations, nonprofits actually have access to the best software tools money can buy. Salesforce, NetSuite, Google, Microsoft, Adobe, and others give nonprofits amazing discounts that allow them access to tools companies twice their size can barely afford. I used to (legally) get $20,000 server packages from Microsoft of $200. Google gives $10,000/month ad-word grants. SalesForce and NetSuite provide amazing tools at amazing prices.
Nonprofits are right to believe if they had access to better tools and more money they could do even better. Tools written for nonprofits tend to be second rate (look at the vast majority of fundraising toolkits), and they are held back in the places where they need specialized software. I have friends that write this stuff, they work hard, but with literally billions less in resources they have a big hill to climb.
Organizations like N-TEN have been helping nonprofits learn from each other and from the best of the for-profit world for nearly 15 years. That community has benefited thought leaders like Beth Kanter, John Kenyon, Ryan Ozimek, and others who help NPOs focus on their goals instead of their tools.
For-profit marketing staff do not believe they have anything to learn from nonprofits, and are often making mistakes that the subject of basic talks at conferences like NTC 5 years ago.

Nonprofits often struggle to figure out the right way to leverage new tools because they try to leverage them first. When traditional companies start trying to market in new spaces they sometimes make it look easy because they have a path to follow. A path broken by nonprofits.