Skip to main content
  1. Posts/

Documenting Requirements - A Few Thoughts

·9 mins

Even after being in development projects for more than a few years now, I am always not far from being awe-struck at every requirement phase we have had.

The process of gathering and validating requirements, and converting everything to specs that a developer can understand, and maintaining traceability through all the rewrites and changes - are the most critical phases that always excite and worry me at the same time. Documenting all these in a language that finds common acceptance across user groups (& probably, across cultures) is, well, crucial to say the least.

Specifically in Customer relationship management (CRM) systems, many projects fail to deliver the desired outcomes and return on investment. While CRM systems are essential to put customer at the core and center - from managing sales pipelines, marketing campaigns, through customer service, the enablement process is far from being consistent. One of the main reasons for CRM program failures is attributed to the lack of clearly defined and validated requirements early in the project (tagged to clearly articulated benefits - story for another day).

Without clear requirements guiding the process, miscommunications, scope creep, and misaligned expectations are inevitable.

This article will examine the importance of putting in the time and effort to gather and document detailed CRM requirements upfront. Clear requirements act as the foundation for successful CRM implementations that solve real business needs. They minimize costly rework, keep stakeholders aligned, and provide measurable goals to validate the solution. By following best practices around requirements gathering, organizations can set their CRM projects up for maximum value.

Why Clear Requirements Matter for CRM Projects? #

The reasons to document requirements are many, but the most important ones may be summarized as below.

  • Reduce miscommunications between stakeholders: Documented requirements leave little room for assumptions and interpretation errors across different teams involved in a CRM project, including business users, IT staff, external consultants, and vendor partners. With a shared understanding upfront, inefficient back-and-forth is minimized later on.
  • Ensure solution addresses actual business needs: CRM requirements rooted in the organization’s specific workflows, processes, and objectives ensure the final system maps to real-world needs rather than just best guesses. This alignment is critical for user adoption and ROI.
  • Provide measurable metrics for testing and validation: Concrete requirements around features, capabilities, integrations, and performance provide defined acceptance criteria to test against. pass/fail metrics enable the organization to objectively evaluate the CRM solution prior to launch and ensure it hits the mark for all aspects deemed mandatory.
  • Minimize costly rework down the line: Reworking and retrofitting an already-built CRM system is exponentially more expensive than investing in detailed requirements upfront. Quality requirements significantly reduce the odds of having to rebuild or patch together solutions due to missed requirements, which eats away at project budgets and timelines.

Best Practices for CRM Requirements #

While we have tackled the “why”, putting the guidelines to practice for every individual project has been an uphill battle.. even for consulting companies. There may be highly documented proceesses, entire books written on the subject, but the fact remains that the process is not a one-size-fits-all.

Identify all relevant stakeholders early and include them in process #

Determine who the core internal stakeholders are — across business, IT, executive leadership, etc., and include them in requirements workshops ensures broad organizational needs are captured. The process of gathering and documenting requirements across stakeholders from business, function and technology domains. Externally, integrate vendor perspectives and identify dependencies with third-party systems.

Utilize mix of interviews, surveys, workshops to gather input #

Leverage different modes of eliciting requirements from various sources. One-on-one interviews allow for deep dives into individual viewpoints while broader surveys and workshops facilitate big-picture thinking and consensus building.

Document functional vs nonfunctional requirements #

Capture the core capabilities and features the CRM must perform along with more technical nonfunctional elements like performance, security, compliance, and integration needs. These two classes of requirements provide a comprehensive view. We will come back to more of documentation practices in a bit.

Specify system capabilities, integrations, security needs #

Drill down into the specifics around workflows, data models, business logic, security protocols, integrations with other enterprise systems, and APIs. Detailed requirements in these areas are imperative.

Set measurable goals and KPIs for desired business outcomes #

Quantify what success looks like for the main business drivers behind the CRM project. Establish baselines and target KPIs around revenue growth, customer retention, campaign ROI, etc. to objectively evaluate success.

Prioritize must-have vs nice-to-have features #

Classify each requirement on level of necessity so that trade-offs can be made intelligently if needed. Separate the bare minimum from the nice-to-haves.

Use visual models like user flows and wireframes #

Supplement written requirements documentation with visual depictions of user workflows, page layouts, integrations, and data architecture. These help crystallize abstract concepts.

Establish traceability back to business goals #

Link each requirement to one or more high-level business goals so that everything maps logically back to tangible benefits and outcomes. This traceability validates true need and helps align teams to the true path / bigger picture.

Putting everything to practice: Documenting Requirements #

When documenting requirements, it is useful to start from a template, but it is equally important to make sure that the template is not a hindrance to the process. The template should be a guide, and not a rule. The following are some of the key sections that I have found useful in the past.

A few documentation practices that I have found useful in the past are below.

Structure and Language #

Structure and language are the two factors cause the max impact to the requirement document, and simple in hind-sight. The structure is fairly straight forward - you just group user requirements into buckets, and order it in a way that makes sense to the stakeholders.

Evaluate each statement of a requirement against the following list to apply the “few good rules”.

  • Correct: The term speaks for itself, doesn’t it?
  • Complete: Should not be open-ended, and should carry forward on its own weight to functional spec
    • Avoid use of “including …”, “not limited to "
    • Don’t make subjective or vague statements
    • Avoid use of ‘TBD’, but do ‘TBD’ may not be completely eliminated at the very beginning part of the process. If you have to use it, make sure you clearly state factors that have caused the exercising of that option and describe the conditions that will remove TBD
  • Consistent: Consistency in description, language, and functionality expectations
  • Bounded: Measurable conditions have to be described and relative statements have to be avoided. “System shall provide response time less than or equal to 5 seconds” is better than “System shall provide quick response times”
  • Unambiguous: You cannot have a requirement listed but at the same time excluding from scope

While the use of language becomes a hot debate in some circles, I try to apply simpler rules:

  • Use of “shall” (vs. use of “will”)
  • Use of definitive sentences that are deemed complete. Do not use “etc.”, “including … " and such terminologies which leave things to interpretation or imagination
  • Avoid usage of double negatives in a sentence
  • Simple to understand and well articulated

Each requirement should be unique in the set of requirements identified for a project or a program, and be identifiable as such. Inputs from all stakeholders - business and technical teams, and consideration of external environmental factors (regulatory policies, organization strategy etc.) are equally necessary. At the same time do not include designs to address a problem or solutions in the requirement document.

Handling Changes #

This is a separate section since this is what we dislike the most. While change management by itself can be a clearly marked process, do you articulate on how to carry forward these changes to the requirements documentation? An indication of versioning of requirements document, and scoping of individual projects that align with the overall requirements go a long way in bringing enough clarity here.

Important Sections #

While customers are free to exercise right on the template structure, it is imperative for us to make sure it has a place for some important sections.

  • Business Rules and Business process diagrams: While not separate sections, making them part of the core requirements, or wherever needed, will help everyone to stay on the same page. Especially in case of COTS products, implementing business rules will demand a big share of development effort
  • Non Functional requirements: Everything that is deemed important other than the core business requirements - like performance of the application, security requirements, usability requirements and supportability requirements have to be articulated. Even if the customer does not have this practice, it is never late to educate them and include such requirements in order to bring in enough clarity to business expectations
  • Regulatory requirements: This is applicable and really important for certain industries like Life Sciences that are subject to intense auditing. For a newly proposed system, or even for changes to an existing system, capture and document requirements around regulatory considerations
  • Assumptions: Clearly categorise assumptions while documenting them

The above points should act as a starter, but can no way be deemed comprehensive. Documentation standards available from IEEE standards talk about some of these and much more - for software requirements and specs. Evaluate them if you have access to the artifacts - that will be time well spent on establishing standards ourselves.

Common Pitfalls #

Shortcuts are alluring, oversights happen and project constraints are a thing. The following are some of the common pitfalls to avoid.

  • Not validating requirements with end users Failure to review requirements with the actual end users who will leverage the CRM day-to-day risks developing a system that does not match real workflows. Continuous validation ensures stakeholder consensus.
  • Allowing open-ended creep As new requests come in (within a project or in a sprint), they must be prioritized against original requirements to avoid uncontrolled growth or change. The change control process does not always need to be rigid but should establish a common framework to accept changes by consensus and through thorough evaluation of impact vs. benefit
  • Lack of specificity in documented requirements Ambiguous, vague requirements leave too much open to interpretation, often resulting in capabilities that do not address the real needs. Details are critical.
  • Not keeping requirements updated as project evolves Requirements documentation should be a living artifact, updated as changes occur. Outdated requirements equal misalignment.

Further Reference #