📔 Documenting Slate

If you’re just implementing Slate you don’t need to document everything you’re doing, because you’re doing a ton. However, documenting the big decisions you’re making now can be a huge help later. Prioritize documenting the following items:

• Big Decisions

  • You’re thinking through some foundational architecture for your Slate instance right now. Once enough time passes, literally everything will be questioned. If you document now, you will save time relitigating these decisions later. There was a reason you created one workflow instead of several different workflows (or vice versa). Help yourself and your coworkers out by documenting why you did that while you still remember.

• Annual Maintenance

  • What are you configuring now that you know you’ll need to update at least once a year?

    • This may include periods, rounds, entry term prompts, populations, application logic, etc.

• Adding or Removing a Program/Major

  • I have yet to see an instance where all you need to do is add a prompt. You may also be updating prompt conditions on forms, updating rules, updating application logic, creating new mailings, etc. You’re going to be doing this often, but maybe not often enough that you’ll remember everything that needs to be done. Be your future self’s hero.

• Bin Movement

  • You may think your bin movement rules make sense without any documentation, but I assure you they do not. In addition, bin movement rules tend to get revised incrementally over time. By documenting where you started, you give yourself a place to document the changes as they happen so that you're not left wondering, "What happened?" a few months or years later.

You’ve been in Slate for a while and you’ve done a lot. The thought of building out documentation is overwhelming. Where do you start?

• Cycle Prep

  • As you do your cycle prep, make note of what you’re doing and when it needs to happen. If something goes wrong, take the time to update your documentation so that same thing doesn’t go wrong the next year.

• Projects

  • Try documenting your next project. Don’t worry about making your documentation perfect. Having something is 100% better than having nothing. Document the modules in Slate you’re touching as part of the process. Make special note of custom work you’ve done like adding custom css, scripts, etc.

• Frequent Questions

  • You know your instance and your users. What are the questions you get asked over and over again? What are the problems that pop-up in your instance? Get those questions and answers typed out to help yourself, your users, and anyone else who may need to work in your Slate instance.

• Permissions
  • Trying to decipher a permission structure built by someone else can take a ton of time and unintentionally leave users either without essential access or with access to sensitive information they shouldn't see. Taking time to write out not only how your roles are configured, but also how you are using populations and realms, can save a lot of time and frustration in the future.