I can't believe there's controversy IF vendors should provide solution documentation & to what extent. Last year a vendor told me "we don't document because its hard & customers never ask explicitly". Then these losers modify 1000s‼️ of objects and leave thinking they're heroes.

Let's be clear. Solution documentation is ABSOLUTELY NECESSARY, and admitting that "dOkUmEnTasHuN iZ hArD" is absolute loser-think. ONLY a loser would give up an opportunity to stay sticky with a customer. I always cross reference my docs with new releases, informing past customers where they can adjust or capitalize. LOSERS leave clients empty handed. Their sales teams have to work 5x as hard for reasons to stay connected.

Here's how I document. Why listen to me? Because I've been doing this over a decade. As late as last week I talked about a 10 year old document I wrote with a peer. My docs LAST.

MY KEY ASSUMPTIONS

• I write for product owners or architects, not devs. I'm not here to explain every code line in exacting detail. I give summaries of solutions built with a library of objects they can view for themselves
• Documenting solutions is not documenting CODE. I document code in code via comments & good variable names.
• Documentation isn't linear. I make frequent use of in-document hyperlinks to artifacts or other sections.
• Document WHILE building. It's at least 10x faster... but probably more like 50x. Explains how the document is laid out, so they don't have to approach it linearly. You'll see how I make separate sections for modified OOB objects, or things that should be reviewed each upgrade. Sample:
  
  There is always a gap between a customer's origin & destination. Some concepts are just *difficult* for them to grasp at scale. I use this section to review concepts that caused difficulty during deployment. In the example below, the customer had difficulty grasping Teamspaces, ITBM Roles, & multiple assignments for Project Tasks. Someone has to continue the education, and only losers abandon them at the end of a deployment.
  
  Of all configurations/customizations in a deployment, some are more important than others. This section outlines solutions that were highest political profile, farthest deviation from OOB, etc. Notice in the Index how I've listed specific solutions. Now we need to know the anatomy of a solution document.
  
  Remember, a deployment may deploy multiple solutions. This is how you document each one. Notice the components of the large sample below
• Summary: WHY did we build this solution, GENERALLY how does it work, a plain description of logic or workflow (use appendices for any diagrams), dependencies, & reports. You may also describe multiple personas that interact with this solution.
• Components: I list new tables & fields, security ACLs, UI objects (forms, client scripts, UI policies, etc), business logic, & reports. I hyperlink each object's name to its associated object in DEV.
• Stories: These are the justifications for all the features built for this solution. Loser-think is telling customers "just read the stories"... its like leaving them with a stack of needles to find a needle in. I place the stories in the context of a solution. Stories hyperlink to the story records in Prod. Oh, your vendor is writing stories in sub-prod? Tsk-tsk-tsk.
• Highlight OOB Edits: Not pictured in this example, but I do a background highlight in red for any object that's OOB that needs to be edited. You should HATE doing this, but sometimes its necessary. Increase visibility in the documentation.
  You're very likely to create new fields, new reports, adjusted notifications, etc. I use the same Anatomy section above but applied to the entire module. See my example for the Demand modifications I made. Same sections, all hyperlinking to the actual objects in DEV. Stories hyperlink to the relevant PROD records.
  
  As stated earlier, you must hate having to edit OOB objects, but if you must, summarize them all in a new section, even if you've listed them in previous solution anatomies. This is so the customer can find ONE place to find all possible future collisions. The "

dOkUmEnTasHuN iZ hArD

" losers have no idea how much customers appreciate this. I list & hyperlink to the objects in Dev. I classify the domain of the object (usually the table its in). I relate it to any of the major initiatives defined in Step 3, then write a justification (I also link to stories here if they're available {and they should be!})



Look, I'm a realist. Sometimes the solutions built aren't the smoothest things in the universe. Other times you KNOW ServiceNow will eventually build something similar, they're just a year or three behind. List the likeliest places for upgrade drama or opportunity to adopt more standardized solutions. The "

dOkUmEnTasHuN iZ hArD

" losers REALLY lose here. I've used this section to contact customers once or twice a year. An evergreen excuse to check in and possibly provide more value. Don't take MY word for it. Ask your sales team how much they'd pay for a GOOD reason to contact existing customers 2x per year. Now tell them you're not going to provide that because its too hard.

A picture is often worth 1000 words. I frequently diagram or illustration to help customers understand concepts & solutions. Now's your opportunity to memorialize them. In this example the customer struggled with the relationship between ITBM roles & Team Spaces. Appendix 1 was an illustration for future reference.

Taking my content survey helps me navigate what to create. If you'd like to sponsor my content, reply to this message for options & rates.

If you get tremendous value, consider a donation. If not, I still greatly appreciate your readership.

If you or your team need a coaching session, book me on Superpeers.

VICTORY through superior design and story telling friends.

I remain yours truly,

Robert "The Duke" Fedoruk