I’ve been running Sitecore development teams for 15 years here in Boston. During that time I’ve seen in-house libraries grow, mature, get neglected, and get replaced. I’ve also consumed my fair share of Marketplace modules, open-source code and blog post examples. The inconsistency of the quality, documentation, and implementation of what I’ve run across was a large driver in the creation of Constellation, and this website. Today I want to share my observations about managing an above-average sized developer toolkit.
Keep Installation as Simple as Possible
Sitecore modules tend to have three distinct concerns:
- Source code
- Configuration files
- Serialized Sitecore Items (packages, Unicorn, whatever)
This typically means a 3-step install process, which means three opportunities for user error. Depending on what your module does, one of these concerns may be a prerequisite of another, which further complicates installs.
My Recommendation
- Use NuGet to deploy all assets to the programmer’s solution in one go.
- Ensure your config files have default settings that will prevent the programmer’s install from breaking without intervention.
- Use Constellation.Foundation.PackageVerification to push any required Sitecore Items into the target Sitecore installation when the module is firtst deployed.
- Make sure that your code fails gracefully if it’s missing configuration settings or required data items.
- Make sure that your module logs a detailed error message if there’s something missing – Items, code, or config.
If you follow my advice, the developer has exactly one installation step – Grab the module off of NuGet. Everything else is optional.
Ensure the Module Works as Soon as It’s Installed
It’s not enough to have your module deploy all components at once. If the module doesn’t do anything immediately after installation – i.e. some additional steps are required – programmers are more likely to go astray.
Sometimes your Foundation or Feature needs a Project level implementation, but if at all possible, provide an test/example/reference implmentation in your package that the developer can exercise immediately after deploying your module to verify installation success.
My Recommendation
- Installation instructions should include a process to verify that the module is installed correctly.
- If at all possible, the new module should just “do its job” by default, without any programmer intervention.
- For Foundation or Feature modules, provide a sample implementation that can be exercised after installation.
Aside from verifying a successful implmentation, modules that start working immediately are easier to adopt into a programmer’s tool kit. You’ll get a higher subscriber rate.
Ensure the Module is a Good Sitecore Citizen
Many Sitecore installations today have been worked on by more than one set of developers. You can find installs with three or four sites where each site was developed by a discrete Sitecore partner. All partners tend to have their own toolkits and best practices.
My Recommendation
- If at all possible, make your module opt-in rather than a global customization.
- If your module modifies the Content Editor or Experience Editor, ensure it only runs on the CM server. Use Sitecore Configuration to disable it on non Content Management roles.
- Your module should explicitly require information about the context it is allowed to execute: server role, index, database, site, language, security.
- If at all possible, make scope definition part of the Sitecore configuration for your module. For examples on how to achieve this, see Constellation.Foundation.Contexts.
- Your module should never run outside this explicit context.
These recommendations apply specifically to modules that modify the HttpRequest/Response pipelines, or interface with any of the MVC pipelines. Too often I see one partner’s toolkit poisoning another partner’s implementation, or worse yet, breaking the Sitecore content editing experience. Define a scope for your module and force the developer to specify it.
Follow Sitecore Traditions Whenever Possible
Your module should look like it was built by Sitecore. Take advantage of their framework and best practices. Doing this makes your module easier to understand, compliments the programmer’s Sitecore reflexes and builds trust.
My Recommendation
- Use copious Log entries – Debug, Info, Warn and Error.
- If your Module is particularly chatty, consider a dedicated Log file.
- Avoid using AppSettings. Use Sitecore configuration syntax.
- Create your own Sitecore configuration section.
- If your module only needs one configuration setting, use a
- Sitecore Settings element.
- Ensure your Sitecore configuration supports the sc:role and sc:env attributes.
- Use Helix conventions for storing Sitecore Items.
- Make sure your Field names are unique to your module.
- Avoid common names unless your module is Foundational.
- Ensure you aren’t duplicating the name of a Sitecore Standard Field or Item property (ex: Name, Icon, Type, Image…)
- Put Sitecore CM components in the right namespace
- Pipeline handlers go in “Pipelines”
- Event handlers go in “Events”
- Rules and Actions go in “Rules”
- Make sure any package dependencies match your target Sitecore version, particularly Newtonsoft.Json and Microsoft.Mvc related libraries.
No One Reads the Manual
When you publish via a NuGet package, there are lots of places where you could put your documentation: the *.nuspec file, a readme.md in the GitHub repository, the *.config files, the GitHub wiki function, or you could roll your own documentation site like I did.
My Recommendation
- Put the documentation everywhere.
- Assume no one will read any of it. Make sure your module will work if the only thing they do is download the NuGet package and “hope”.
- NuGet *.nuspec files have a very short allowed total file size. Use them to describe your package in brief, and provide instructions on where to look for the manual.
- NuGet *.nuspec files have dedicated elements for repositories and websites (where one would assume you could find documentation). Make sure they are filled out and accurate.
One of the reasons I ran my own website was to have better content entry control. GitHub’s wiki feature is okay, but it’s a little basic if you want to include sub-chapters, lots of inset images, and the like.
Config Files are Great Documentation
Sitecore has the best configuration files in the industry. The comments preceeding each section give an excellent idea of what the config section is for, what the defaults are, and why you’d want to change them.
My Recommendation
- Follow Sitecore’s lead.
- Your Config files should serve as standalone documentation.
- your *.nuspec file should refer to the *.config files for additional documentation.
- Document every possible setting and the conditions under which you’d use them.
- Specify that your *.config files are read-only.
- Make sure your *.config files are in the right Helix folder so that they get loaded at the appropriate time during startup.
Just like Sitecore, any *.config file you distribute via NuGet should be treated as the “default” settings. Any modification should be done through an external sc:patch file in the appropriate Foundation/Feature/Project folder.
The practical reason for this is that installing updated versions of the NuGet package will override the “stock” config file. The programmer will lose their local changes.
Write an Excellent Manual
While you should assume no one will read your documentation without an invitation, it needs to exist.
Provide documentation of every aspect of your module. Doing so will force you to identify every possible use case and probably identify some edge cases you weren’t aware of when you were happily writing code in Visual Studio. Having thorough documentation also allows you to point frustrated or confused programmers at a pre-made answer. Documentation can help avoid a barrage of frequently asked questions.
Documentation also improves your module’s street cred by appearing professional. It also will provide some passive internet marketing to help adoption.
My Recommendation
- Write extensive and explicit documentation.
- Host it on a website where it can be available to developers without forcing them to download and install the module.
- Ensure your *.nuspec file references the documentation website.
- Ensure your readme.md file references the documentation website.
- Keep your manual up to date if you make changes that affect implementation.
- Announce the location of your manual on LinkedIn, Facebook, Twitter, etc.
- Announce any changes in documentation along with any new version release.
Listen Closely to Developers
You are the only one on the planet that knows exactly why you module exists, and its intended purpose. Programmers will look at your module with assumptions on how it works, what functionality it actually has, and when it is applicable.
If at all possible, engage programmers directly to hunt for places where your functionalty needs to adjust to better suit the thinking of your consumers.
My Recommendation
- Utilize GitHub’s built-in communications tools to maintain contact with your audience.
- If you’re discussing things with your constituents offline, strongly suggest they record their bugs and comments in GitHub’s tools.
- Respond to questions quickly.
- Identify bad assumptions from your constituents and decide whether to correct their assumptions or adjust your code.
Stay on Top of the Sitecore Release Schedule
A new release of Sitecore is a new marketing opportunity for your module.
My Recommendation
- Update your module to work with the latest version of Sitecore as soon as Sitecore publishes their release. No one trusts out-of-date Sitecore modules.
- Your module’s version numbers should match Sitecore’s major/minor version numbers. This makes it painfully clear to developers which version of your module works with their version of Sitecore.
- Release a new version of your Module to support Sitecore’s latest and greatest? Announce it with posts on all the popular Social channels. Write a blog post, and don’t forget to update your manual.
Conclusion
Writing a reusable Sitecore module and distributing it to the public is far more than a few clever lines of code. It’s the due dilligence of thoughtful packaging, thorough documentation and community awareness that makes the difference between an “accepted-best-practice” tool and another dusty entry in the Sitecore Marketplace.
Final Recommendations
- Enlist friends and co-workers to help identify your module’s features as well as help you with quality assurance and marketing.
- If your module is big enough to support multiple contributors, delegate the workload!
- Encourage contribution in lieu of feature requests! That’s the beauty of open source!
- Encourage contribution vigorously, praise any level of participation with deep and meaningful thanks. Establish a relationship with your constituents. This helps improve visibility and trust in your solution as well as prevents your solution from being forked by someone who liked your idea, but didn’t know you were a team player.