also@medium.com Archives - Page 2 of 7

Written Instructions image by https://www.pexels.com/@markus-winkler-1430818/

Document Like You Don’t Know the Subject

June 30, 2023July 7, 2023Scott S NelsonLeave a comment

(Feature image credit: Markus Winkler)

“All books are just the same letters in a different order”. -Unknown

I know I originally heard this (paraphrased) quote from a comedian. I thought it was Stephen Wright, though I was unable to find this attributed to any comedian on Google. The closest attribution I could find is to the author Cornelia Funke: https://quotefancy.com/quote/1197597/Cornelia-Funke-Weren-t-all-books-ultimately-related-After-all-the-same-letters-filled.

Point being (my regular reader knows I wander off point often, and hopefully entertainingly so), I think that many people tasked with writing documentation think that all the information is right where they found it, and that anyone else can do the same research and come up with the same understanding. To counter that view, I point you to the news and whatever thing people are doing or saying in large enough numbers to be noticed while the vast majority realize that nothing could be further from the truth.

The thing about documentation, the numbers are generally the opposite, in that only a few understand the need to be specific, explicit, and concise.

The trick that has always worked for me is to write the content, then follow the content as if I had no previous understanding of the topic.

When possible, I prefer to go one better and find someone who really does have no understanding and ask them to follow the content. My greatest success with that method is when I created a 20-page document (with lots of screenshots) that walked developers through the sequence of steps to become productive in working with an enterprise J2EE application with authentication and external system integration. The goal was for new developers to complete the process in under 30 minutes with no assistance. My final test of the documentation was when I gave it to our visual designer who completed the process in 40 minutes with no help other than the document.

At the least, I always try to get at least one consumer of the documentation to go through it and provide feedback. When possible, publish the documentation to a platform that encourages feedback. Even better if peers are allowed to edit and revise on their own.

Finally, when comments are edits are made, it is best if the platform provides an alert mechanism so that the content owner can review the changes or comments.

One way to keep documentation fresh

June 29, 2023July 14, 2023Scott S NelsonLeave a comment

Documentation should always have some built-in capability to receive comments and the comments should generate alerts to the content owners.

This process can vary greatly. In some contexts, readers can be allowed to edit the content. Or only some users. Those edits should still trigger alerts to the content owners for review.

Documentation often becomes stale because there is no easy way to communicate changes. Capturing improvements or updates at the time the document is used is the next best thing from when the content needs revision because what it describes has changed.

Bonus approach

For software documentation (especially for enterprise applications), if you use any kind of ticketing or kanban-style stories, include “Create/Revise Documentation” as a standard part of the Acceptance Criteria in your template.

Enterprise Salesforce Team Recipe

June 29, 2023July 7, 2023Scott S NelsonLeave a comment

This is a stream-of-consciousness consideration of SaaS vs Custom vs Budget for organizations that use Salesforce CRM products

The best practice in Salesforce when providing a feature to users is to first look at the standard components, then in App Exchange and if neither of those have what you need, build it yourself (or have a partner build it with you). This is repeated over and over again in articles, videos, and training content developed about how to get the highest ROI using Salesforce. So why is the question asked so often, and why do some many organizations follow the least beneficial path in response?

One reason that seems drive a lot of decisions is that because each business has its unique factors that it requires a unique solution.

Another common reason often cited for custom development on top of Salesforce is that their needs are “not supported out-of-the-box”. This is sometimes elaborated with “we tried to use it out-of-the-box, but it didn’t work”.

The reality is that these organization, at some level, chose a Software-as-a-Service solution as the best value to fulfill CRM and related needs. This is an architecture to go with buy-before-build where most of the needs have already been paid for. In a well-managed enterprise architecture, any custom development once the buy-before-build principle has been realized with the selection of a SaaS solution requires an exception case.

The reasons often present for the exception case of building custom within Salesforce (when a case is presented) seem perfectly valid. If the product doesn’t provide the functionality required, custom is the way to go. What requires more consideration is how this conclusion was reached.

Sometimes it is made by stakeholders with no SFDC administration experience doing a search on the-search-engine-everyone-uses and coming up empty. It is a seldom acknowledged understanding that searching is a skill and that, like driving, it is not uncommon for people be more confident in their abilities than the evidence warrants. The next level of problem with this criterion is that being skillful in searching in one area of interest will not always translate to searching other topics. One factor that may not be (though should be) common knowledge is that the results of the same search can vary greatly when run from different user accounts. The search engine “learns” the types of results the user usually responds to and will provide the results prioritized based on previous searches.

The same issues with search can carry over to stake holders who do perform administrative tasks in Salesforce on a regular basis. Further, the predictive prioritization provided by the search engine will include what the majority have followed, whether it is the most correct or most accurate response to the query.

A scenario that is as likely as the subject matter neophyte searching for answers is when the search is performed by someone who is skilled in custom development. Here the same factors come to play both in how the questions are asked, i.e., “how to develop [solution x]”, how the search results will be ordered (based on most frequent selection of past results focused on custom solutions) and the fact that many developers build custom solutions because they prefer not to use administrative functions.

Salesforce has been refining their capabilities since 1999 and have been very successful at it. That success is not because they missed their customer needs most of the time. There are many organizations that are paying a huge premium in maintaining their custom solutions because insufficient due diligence was performed before customizing.

This isn’t to say that customization isn’t sometimes well warranted. There are many unique needs for solutions on the Salesforce platform, and it is why the Salesforce platform is as flexible as it is.

A well-architected and managed Salesforce org will have a mix of admins to developers that is at least even, if not heavy on the admin side. Depending on the size of the org, either the role of architect can be an external consultant, or the full-time architect will work with external development teams for the occasional custom requirement.

One misunderstood Salesforce certification is the Platform App Builder certification. It is listed in both the Administrator and Developer career path definitions, and it favors entirely meta-data-based solutions. This is how the out-of-the-box capabilities provided by Salesforce can be “customized” without having to maintain custom code. It also allows for developer to create custom components that can fill in any minor feature gaps that can be managed by administrators after development.

Many organizations are struggling with staffing competent and experienced Salesforce developers when there are many skilled administrators out there than can help an organization make better use of their original decision to buy rather than build.

You can always get there from here

June 15, 2023July 7, 2023Scott S NelsonLeave a comment

There are many quotes to the effect that perfection is a path and not a location (my wording in this case). To me, this is the essence of agile vs waterfall (and, to a degree, SAFe).

Agile trusts that high performing teams, following processes that support continual re-evaluation, will produce higher quality deployable results with the same amount of resources.

All methodologies have processes (or ceremonies). Properly followed, they can all produce good results. Whether one methodology will produce better results than another is fairly moot, because it isn’t the methodology alone that influences the results. It is where the focus of the team is while following the methodology that makes the difference.

A team that is focusing on a date will almost always have to skip some steps to make that date.

A team this focused on the completed product is almost always going to miss an import use case (very simple products excepted).

A team that is focused on absolute perfection of every task is going to miss business expectations.

A team that is focused on sticking to an iterative process and willing to course-correct their approach to improve the next iteration will always produce better deliverables.

Leadership is less about providing direction and more about communicating where the team should focus to be successful. The goal is to have a shared vision and foster the flow state that will support realizing some version of that vision at regular intervals.

Or, to use another similar quote, “This is the way”.

Email Best Practices

April 10, 2023November 18, 2023Scott S NelsonLeave a comment

There should be books written on this topic. Many, and all with fewer than four paragraphs or no one will finish them.

Manage email subjects

Whenever someone is compelled to label something as “common sense”, everyone agrees even though it is clear that it is not all that common because it had to be called out. That can apply to just about anything I have to say about email. So here are a few common sense concepts about email:

Keep the email to a single topic

While some people are good at making context shifts in a conversation, there are many people who find switching topics difficult. In verbal communication a missed context switch will often result in a response being framed in the previous context. The same can happen in emails, or (worse) the new context is simply ignored. Why is it worse when ignored? Because when a subsequent email requests a response to the ignored/skipped topic, the recipient will either again miss it or reply that they have already responded. This is neither obstinance nor resistance; it is how their brain perceives it. Keeping to a single topic may initially seem inefficient (and it is if you know for a fact the recipient is good at context management) yet it is far more efficient to write three emails and get a congruent response to each than to write one email followed by a chain of a dozen follow ups that may or may not conclude in everything being answered.

I feel so strongly about this, I wrote a longer rant recommending to Keep Emails to a Single Topic a year ago.

When the thread changes topic, change the subject.

Even congruent email chains can move from one topic to another. If you are the one writing the email with a topic change, change the subject in the email, even if you do retain the earlier thread as a related reference. If someone else changes the topic, update the subject in your reply with [New Subject] (was re:[Old Subject]. When you go to search your email for a thread several weeks later, you will be glad you did.

Trim to fit

When replying to an email where many people are on the thread, remove the list of recipients from the original email, especially when updates are inline (another bad practice).

Many more tips to come…