On Desire Paths Through CiviCRM: Use Cases, Capacity for Appropriation, and Collective Knowledge Infrastructure

CiviCRM is a free open-source software platform for “Constituent Relationship Management” or “Citizen Relationship Management”, that is, for working with contacts and with processes connected to contacts. CiviCRM provides a large number of powerful tools, but offers only limited guidance regarding purposes or workflows.

Chaz Hutton: Desire Paths. London 2025. https://chazhutton.com

Chaz Hutton: Desire Paths. London 2025. https://chazhutton.com

Although the software has been developed and used worldwide for more than twenty years, its practical appropriation still presupposes considerable prior knowledge. The software is not self-explanatory. It becomes powerful primarily in the hands of those who already possess the knowledge and methods required to understand how and for what purposes such software can be used. Accordingly, the existing documentation remains predominantly feature-oriented and only to a limited extent unfolds along the lines of real-world usage situations. This paper builds upon my reflections in “Toward Overcoming Suboptimal Provision of Free and Open-Source Software: The Case of CiviCRM”. Because there is no systematic representation of the typical ways in which people without prior knowledge solve everyday organisational problems with CiviCRM, the dissemination and practical use of the software remain below its potential.

I therefore propose the concept of the “desire path” as a guiding metaphor for describing functioning modes of use.

Desire paths emerge where people repeatedly take similar routes under real conditions. Applied to CiviCRM, the term refers to possible, not yet formalised ways in which the software is actually used and configured for concrete purposes — for example, to maintain contacts, cultivate relationships, manage processes, organise events, or administer donations.

I attempt to develop guidelines for improved documentation by proposing that the software should be understood from the perspective of the desire paths through which it is used. The metaphor is particularly suitable because usage continuously changes in response to disruptions. Obsolescence, technical problems, or innovations constantly alter these paths of use. Any change in the reality through which these paths run must necessarily feed back into their mapping if documentation is to remain current. In what follows, I therefore seek a unified approach to describing such realities of use, identify recurring patterns of actual practice, and develop ideas for documentation based on desire paths.

The paper furthermore considers the extent to which such documentation must be understood not merely as part of the software’s capacity for appropriation — and therefore as part of the collective good “CiviCRM” — but simultaneously as a possible reference point for a governance structure. Only documentation conceived from the perspective of real-world usage enables the consequences of decisions in software development to be anticipated at an early stage and makes the issues under discussion comprehensible to users affected by such decisions, thereby fostering their intrinsic motivation to participate in governance processes.

Table of Contents

1. The Search for Desire Paths

Anyone seeking to understand CiviCRM should not begin with its functions, but with the paths along which people attempt to solve real organisational tasks using CiviCRM.

On the application layer, one encounters intuitively understandable entities: contacts, activities, relationships, groups, mailings, events, contributions, and cases. Cases are records or processes, that is, sequences of activities in which many contacts may be involved.

In order to work with these entities and relate them to one another, functions of the orchestration layer are required: building forms, processing form submissions, preparing datasets as lists, working further with processed datasets, and automating tasks, to name only a few examples.

The functions of the application and orchestration layers together make possible what can be described on the level of use cases. These are typical tasks that organisations seek to accomplish with CiviCRM. CiviCRM offers many possibilities, but only to a very limited extent predefined solution paths for accomplishing such tasks.

CiviCRM provides all necessary functions, but it does not prescribe one unambiguous solution path for solving a task. Appropriating CiviCRM therefore means finding viable routes for one’s own use case among many possible solutions.

In this sense, the use of CiviCRM becomes a matter for scouts and pathfinders searching for routes and hoping to discover well-trodden “Desire Paths” that reliably lead to the intended results. The challenge lies in the fact that these desire paths are insufficiently documented. While the software itself is freely available, there is no equally accessible and systematic representation of its practical use. Knowledge of the desire paths is unevenly distributed.

This paper does not attempt to develop a complete catalogue of such desire paths. Rather, it seeks to explain why their systematic documentation is necessary and how such documentation might be structured.

2. The Reality of Use

The reality of using CiviCRM is unspectacular. It consists of everyday situations in which people attempt to organise something together — with limited resources, often on a voluntary basis, and frequently under time pressure.

Typical situations can be found in many contexts: in associations, political parties, citizens’ initiatives, church groups, organising and community work, foundations, campaign organisations, refugee support, educational projects, the coordination of voluntary work, and many others. As different as these contexts may appear, the challenges that arise within them are remarkably similar. The recurring issue is always how to organise relationships between people over time and how to remain collectively capable of acting. Such situations can be described scenically.

2.1 Risks of Loss as the Motive of Usage Scenarios

Late in the evening, someone sits at a kitchen table trying to complete an email list. Names are missing, addresses are outdated, and responses have not been systematically recorded.

A volunteer stands at a weekly market, has a productive conversation, and intends to follow up on the contact later — without having a reliable place to record it. In an association, a donation arrives that cannot be clearly assigned. People want to send a thank-you note, but the matter slips from view. After an event, there are participants interested in becoming further involved. Two months later, nobody remembers exactly who they were. Someone volunteers to help. There is no shared structure capable of integrating the offer. The volunteer receives no reply. Three weeks later, the person can no longer be reached.

These scenes are banal. They do not depict exceptional situations, but the normal condition of organisational practice. In each case, there is neither a lack of commitment nor of motivation, and often not even a lack of resources in the narrower sense. What is missing is the ability to preserve over time what once existed: the contact itself and the information associated with it, in a form that remains usable and connectable.

These scenes reveal five problems that must be addressed.

  1. Time is lost.
    Tasks are performed repeatedly, information must be searched for or reconstructed, and processes repeatedly begin from the start. Loss of time is the price of missing structure.
  2. Money is lost — not necessarily in the sense of direct financial loss, but in the sense of unrealised possibilities. Willingness to donate is not recognised, not followed up on, supporters are not retained, and funding opportunities remain unused.
  3. Opportunities are lost.
    Interest emerges, engagement is offered, relationships begin — and then disappear again because no notation exists through which the relationship can be maintained. Opportunities possess a limited time window that quickly closes without an appropriate structure.
  4. Credibility is lost.
    It is easy to say, “We will get back to you,” and then unintentionally fail to do so. Not out of bad intentions, but because the matter slips away. The consequence is a loss of credibility that extends beyond the individual incident itself.
  5. Knowledge is lost.
    What disappears is not merely knowledge of who expressed interest or engagement, but also access to people themselves, to the knowledge bound to them, and to their potential capacity for action.

These five forms of loss — time, money, opportunity, credibility, and knowledge — are interconnected. They reinforce one another. To the resource limitations of a cause pursued with good intentions is added the fact that, without structure, what has been laboriously built up and is in principle already available is quickly lost again.

2.2 Scenic Representation as the Key to Understanding

The historical development of CiviCRM also becomes much easier to understand when imagined scenically. The components and extensions of CiviCRM are not merely technical categories. They are institutional responses to recurring everyday tasks within organisations.

According to one origin story, the development of CiviCRM more than twenty years ago was partly rooted in door-to-door political campaigning. In such campaigns, it makes a great deal of sense to document conversations in order to address, within later political work, the concerns and hardships encountered in personal interactions with individual households. The necessity of maintaining personal contact with affected individuals, understanding concerns as ongoing processes, and coordinating activities related both to the stakeholders of a process and to the issues connected with them is particularly well illustrated through the example of door-to-door campaigning.

Every other function of the application and orchestration layers likewise possesses such a historical point of origin: for example, enabling people to subscribe to a newsletter or submit a concern through a form on a website. The distribution of newsletters, whether by post or email, presupposes that mailing groups can be defined and contacts correctly addressed. Without the systematic recording of contributions, donations cannot be formally acknowledged. The organisation of events requires the management of registrations and participation. Longer-running concerns lead to the development of process management systems.

Within CiviCRM, support for homeless people is a well-known example of such a recurring type of process. One therefore speaks of “cases”, because cases of homelessness, for example, are managed and supported in this way.

3. Ten Patterns of Actual Practice

The fear of losing time, money, opportunities, credibility, and knowledge compels us to find the best possible ways of dealing with situations in which such losses threaten to occur. In practice, such paths rarely emerge through planning alone. Most of the time, we improvise — not least because the problem to be solved often only reveals itself at a late stage, long after the original planning has taken place. Through the repeated use of once-discovered solution paths, stable patterns gradually emerge. Desire paths, in other words.

Such desire paths through CiviCRM have so far not been formally defined. They are recurring solutions to problems that have proven practicable under real conditions, yet they are rarely transmitted in more than oral form and are usually available only as person-bound knowledge. A typical characteristic of a desire path is that it changes slightly whenever new obstacles or opportunities appear along the route. Individual users adapt the path for themselves without the altered route ever being documented anywhere. Different organisations may therefore develop very similar desire paths even when they use different tools or configurations. The reintegration of these altered routes into documentation inspired by desire paths is therefore ultimately a matter of successful governance within the CiviCRM user community.

Anyone attempting to document desire paths must analyse the real-world use of CiviCRM in order to identify stable patterns of action. Such patterns form the actual core of the practical appropriation of CiviCRM.

At least ten such patterns can be distinguished.

  1. A contact emerges that should become usable.
    A person comes into view — through a spontaneous encounter, an event, or a form submission — and must be integrated into a structure that enables further work with that contact. Without this step, all subsequent processes remain impossible.
  2. Events must be documented.
    A conversation, request, or interaction is recorded as an activity or — if it extends over a longer period and perhaps involves several contacts — organised as a case. Creating a file or case marks the difference between an isolated event and a coherent process.
  3. Processing inputs.
    Forms merely serve as an interface. The actual logic lies in the structured processing of submitted data: it must be determined whether the associated contact already exists or needs to be created, relationships must be established, activities documented, and the substance of the submission recorded — for example, a financial contribution, information about event participation, or information relating to a case. This makes clear that many conceivable desire paths exist for processing inputs, depending on the field of activity of the organisation in whose context CiviCRM is operated.
  4. Transition to automation.
    Events within the system trigger actions: emails are sent, the status of contacts, activities, relationships, contributions, event participations, or cases changes. Documents may also be generated in the process. Such automations are only sporadically predefined by the system itself. They must instead be configured by users in relation to their particular context of use.
  5. Generation and use of documents.
    Confirmations, certificates, or contracts must be created and sent.
  6. Segmentation.
    Organisations must determine who belongs to which group, who should be addressed, and who should not. Such classification forms the basis of almost all further processes, especially communication and automation.
  7. Targeted or automated communication.
    Individual contacts or defined groups are addressed, responses are recorded, and the resulting information is fed back into the dataset.
  8. Modelling states and statuses.
    Processes do not remain static, but move through different states: open, in progress, completed. Defining and tracking these states is crucial in order to avoid repetition, errors, and duplicated work.
  9. Connecting CiviCRM with other systems.
    Real workflows often extend beyond the boundaries of a single system — for example when direct debit mandates are transferred to a bank, accounting data to bookkeeping systems, or information concerning permissions and eligibility to other systems. Data is transferred, processes initiated, and external systems integrated.
  10. Debugging and understanding the system itself.
    Users develop methods for discovering what is happening within the system, why certain things function or fail to function, and how errors can be resolved.

These patterns share one common characteristic: they are not uniquely determined. For many of these problems, several possible solution paths exist, each emerging from different historical contexts. A request, for example, may be modelled either as an activity or as a case; automation may be implemented through different tools; segmentation may be realised through different mechanisms.

Practice is therefore shaped not by clear prescriptions of the software itself, but by the coexistence of competing desire paths through which users attempt to develop viable solutions with the software. Yet this openness of the system means that users are confronted with a multitude of plausible possibilities without guidance as to which have actually proven themselves in practice.

This is precisely the point at which documentation based on desire paths begins: making actually existing desire paths visible, explaining their differences, and formulating, on this basis, reasoned main paths. This approach enables a dual structure. For each relevant use case, a curated main path is described that is regarded as stable and teachable. At the same time, alternative paths remain visible, and the main path provides a reference point for determining under which conditions deviation from it may be sensible.

The advantage of this approach lies in the fact that it makes it possible to reduce and render manageable the complexity of CiviCRM without restricting the adaptability and universal applicability of the system.

4. CiviCRM as a Construction Kit: Use Cases Instead of Functions

If the experience-based patterns of use — most of which are nowhere systematically written down — are transformed into a reproducible and teachable form, what emerges is a use-case library. The appropriation and use of CiviCRM then changes fundamentally. Contributions to such a use-case library do not describe what CiviCRM is capable of in the abstract, but rather how typical organisational problems are solved with CiviCRM under real-world conditions. The object of such documentation is therefore the desire paths of actually functioning usage.

The fundamental building blocks of CiviCRM can thereby be reduced to a limited set of data and action logics: contacts, relationships, activities, groups, email communication, the management of processes or issues — in the form of cases — event organisation, and finally the administration of contributions. These elements structure social reality. Whoever works with them changes states of affairs by combining and understanding these elements over time.

A use-case library likewise requires a synoptic overview of the functional areas of CiviCRM, that is, both the functional areas of the application layer and those of the orchestration layer. Such an overview is useful in order to give learners orientation regarding which tools are available at all and to enable them to understand how these tools can be classified and prioritised for their own purposes.

4.1 Five Criteria for Good Use Cases

Use cases must satisfy five criteria that go beyond a mere overview or description of functions.

  1. The point of departure is recurring situations, not functions.
    Every use case begins with a concrete situation of action, such as those described in the previous section.
  2. Every use case represents a desire path.
    It describes a stable route through which such a situation is typically resolved using the means available.
  3. Every desire path is presented as a combination of fundamental logics.
    The documentation explicitly identifies which entities are involved, which processes take place, and which decisions are made.
  4. Alternative paths are made visible for every use case.
    The documentation may establish one particular path, but through its explicit limitations and through references to alternatives, it also makes clear that other paths exist and under which conditions they may be sensible.
  5. The underlying structural decisions are explained.
    The documentation shows not only how something functions, but also why a particular modelling approach has been chosen.

4.2 Use Cases as “Recipes”

A recipe answers two simple questions: “What do I want to achieve?” and “How do I proceed?” It describes the goal and explains the procedure in clear and comprehensible steps.

CiviCRM likewise requires such recipes.

Typical examples include:

  1. the initial setup of CiviCRM in order to become operational
  2. configuring the connection to an email server and the use of email addresses
  3. importing existing contact data and other datasets into CiviCRM
  4. creating a web form embedded on an arbitrary website that transmits data to CiviCRM, for example:
    1. subscribing to a newsletter
    2. registering for an event
    3. making a donation through a form
  5. connecting CiviCRM to fundraising and payment-processing providers such as Twingle, PayPal, or Stripe
  6. setting up online donations
  7. implementing the collection and submission of SEPA direct debits
  8. organising event registration
  9. sending a newsletter
  10. creating a case, possibly from submitted form data, consisting both of the submitting contact and of the data describing the matter itself

These recipes are already desire paths. Nor do they remain isolated. Rather, they themselves partly constitute combinations of several independent desire paths, or else remain open to combination with others. This already becomes visible in the list above: in order to create a case from a form submission by a website user, several such paths must already have been traversed.

Every recipe may conclude with a chapter securing the knowledge gained through the process. After the practical instructions comes the question: what is actually happening here? At this point, the use case is analytically broken down. The entities, processes, and decisions involved become visible. In this way, a mere instruction manual becomes an object of learning.

This dual structure — execution and understanding — is central to the long-term empowerment of users, who thereby become not only capable of acting, but also capable, through reflection, of understanding what they are actually doing in technical terms.

4.3 From Entry to Mastery of the System

The recipes contained in the use-case library can be arranged progressively according to their level of difficulty. At the beginning stand simple and common use cases with straightforward recipes that can be implemented quickly. Building upon these, more complex desire paths are introduced that combine several recipes with one another.

In this way, beginners initially learn to understand individual elements, while more advanced users learn how to combine these elements into complete workflows. In particular, the less intuitively accessible tools of the orchestration layer — such as FormBuilder, FormProcessor, SearchKit, CiviRules, or the Search Action Designer — no longer appear as isolated functions, but rather as means for combining recipes.

4.4 Roadmap: Building Desire-Path-Based Documentation

The development of such a use-case library can itself be described as a process.

  1. Identifying typical situations of use and describing them in the form of scenes.
  2. Reconstructing the desire paths that emerge from them: how does the process usually unfold in practice?
  3. Bundling, comparing, and prioritising paths.
  4. Elaborating them in the form of use cases and recipes.
  5. Continuous review and revision of the resulting “maps of paths”, ideally in response either to advance notice of upcoming changes communicated by maintainers of components or to feedback from users organised within the governance structure of the community.

This process is not a one-time undertaking, but an iterative one. Desire paths change, new ones emerge, and existing ones lose relevance. The use-case library thereby becomes itself a dynamic element of the knowledge infrastructure.

5. Strategic Perspective: Capacity for Appropriation as a Collective Good

The preceding sections outlined an approach intended to make the practical appropriation of CiviCRM easier for users. The improvement of this capacity for appropriation, however, is not an individual problem affecting isolated users, but a structural phenomenon that can be described as a collective good.

5.1 Capacity for Appropriation as an Undersupplied Collective Good

The ability to reliably master typical situations of use does not arise automatically from merely using the software. It is not self-explanatory, and given its comparatively broad functional scope and the complexity of its possible contexts of use, it can scarcely be expected to be so.

Capacity for appropriation depends upon the availability of knowledge: knowledge about which tasks typically need to be solved, which problems usually arise in the process, which solution paths have proven effective, and how these paths can concretely be implemented.

In practice, such knowledge exists — in the form of experience, implicit routines, and organisational memory. Yet it is rarely systematically documented and publicly accessible. This creates a classical constellation: many benefit from improved documentation and training, but only few possess direct incentives to provide them. The result is a structural undersupply whose consequences include high entry barriers, recurring mistakes, inefficient workflows, and the continued reproduction of the systematic loss of time, money, opportunities, knowledge, and trust, because available software remains unused despite being affordably accessible.

5.2 Implementation Agencies in a Field of Tension

Within this situation, implementation agencies specialising in CiviCRM occupy a particular role. They possess precisely those bodies of experience from which desire paths can be reconstructed: project documentation, support requests, configurations, and recurring use cases.

At the same time, however, they exist within a field of tension.

On the one hand, they possess an interest in improving the capacity for appropriation of CiviCRM. Better documentation lowers entry barriers, increases the dissemination of the software, and creates demand for advanced services such as hosting, operations, support, and consulting. On the other hand, this very knowledge constitutes a competitive advantage. Those who possess tested solution paths can implement projects more efficiently and differentiate themselves within the market. Full disclosure of such knowledge may therefore appear risky.

This ambivalence leads to the frequent result that knowledge about desire paths is only partially published or not published at all. Put simply, there is little incentive to disclose such knowledge in a structured manner. It remains embedded within organisations and is inaccessible, or only partially accessible, to outsiders.

The consequence is an equilibrium that is stable, yet suboptimal for the broader mass of potential users: the capacity for appropriation is not provided to the extent that would be socially desirable.

5.3 AI and the Future of Documentation

With the emergence of AI systems, this constellation changes without the underlying problem being resolved. On the individual level, AI may facilitate processes of appropriation. It can answer questions, suggest probable solution paths, and help users cope with concrete problems situationally. In this sense, it functions as a partial substitute for missing documentation.

On the structural level, however, a decisive deficiency remains:

AI cannot distinguish between merely conceivable or probable solutions and stable, proven desire paths. AI remains incapable of recognising such tested solution paths for as long as they are not documented by users on the basis of actual practical experience and marked as repeatedly successful.

Without an explicit reference structure, however, there is no possibility of classifying and evaluating solutions. Individual appropriation of the software may be facilitated by AI, but this still does not produce a collective knowledge base, nor a governance structure capable of relating the documentation of desire paths both to decisions in software development and to experiences arising from practical use.

At the same time, however, AI opens up new possibilities for implementation agencies. They are increasingly able to analyse their own datasets systematically and extract desire paths from them. This increases the likelihood that the knowledge about usage paths embedded within implementation agencies will become far more accessible and strategically usable for those agencies themselves.

This may lead to a further shift: the knowledge necessary for appropriation not only remains scarce, but may also become increasingly privatised for strategic business reasons.

5.4 Desire-Path Documentation as a Countermovement

Against this background, publicly curated documentation of desire paths acquires strategic and societal significance. It constitutes a form of knowledge infrastructure that counteracts structural undersupply. By making implicit experiential knowledge explicit and accessible, it contributes to providing capacity for appropriation as a collective good.

This is not merely a matter of providing information. Documentation itself exerts a formative effect. It renders certain paths visible, stabilises them, and creates orientation. In this sense, it assumes a function that extends beyond classical documentation. It influences how the software is used by transforming desire paths into institutionalised routes.

5.5 Between Commons and Club Goods

The question of who should sustain such documentation remains open. Incentives for providing it exist, but they are ambivalent. On the one hand, there are strong reasons for organising desire-path documentation as a public good. It increases the overall capacity to use CiviCRM, lowers entry barriers, and improves the efficiency of organisational practice.

On the other hand, the costs involved in maintaining such knowledge create incentives to organise it as a club good — for example within an association — and thereby render it accessible in a more exclusive manner.

Actual development will likely unfold somewhere between these two poles. What matters is not striving for a complete solution, but taking concrete steps that move in the direction of improving the provision of capacity for appropriation. Knowledge that becomes available in this way will then tend, over time, to become part of the collective good itself once it enters the core systems maintained by the community, which are either directly or indirectly subject or committed to the principles of the GNU Affero General Public License v3.

For this reason, it appears sensible to pursue a dual strategy.

In the interest of sustainability, of affirming existing structures, and of strengthening governance, work should be undertaken to systematically review the documentation available at docs.civicrm.org, expand it in accordance with the idea of desire paths, and revise it where appropriate in order to establish greater continuity with the actual reality of desire paths.

At the same time, however, a potentially disadvantageous challenge for the wider community of possible CiviCRM users lies in the fact that this documentation is maintained through a Git-based workflow built upon Markdown files, requiring access to the GitLab instance maintained by the CiviCRM community as well as familiarity with working with Git itself. See CiviCRM developer documentation on contributing to docs.

For the overwhelming majority of users, this constitutes an excessive burden and therefore a very high barrier to participation. If desire-path documentation is to be taken seriously as a hinge point of governance, a complementary and lower-threshold alternative for participating in documentation from the perspective of users will need to be developed.

5.6 Perspective: The Question of Appropriation as Part of the Collective Good and Its Governance

The question of how CiviCRM is documented and communicated is not merely a technical or didactic question. It is a question of the organisation of knowledge — and therefore a question of governance.

In my view, the development of a desire-path-based use-case library constitutes an integral component of the provision of CiviCRM as free software insofar as it renders the property of capacity for appropriation available and collectively workable as a collective good. It connects the technical possibilities offered by the software with the reality of social practice, and individual use with collective knowledge formation.

This text was originally drafted in German. This translation was produced using ChatGPT.

The original version can be found at https://plinubius.de/auf-trampelpfaden-durch-civicrm-use-cases-aneignungsfaehigkeit-und-kollektive-wissensinfrastruktur/