Definitive guide for how things should be done

[joyfulmantis]

There are a bunch of decisions where there are multiple solutions with different advantages and drawbacks.

Some of the issues I have stumbled over so far have been:

• The appropriate scope of individual plugins. When to write your feature into an existing plugin, and when to write a new plugin. For example: Should plugins that refactor code be written into the hls-refactor-plugin, or be standalone plugins?
• When should projects use use vs useWithStale vs useWithStaleFast. For example, should a plugin that modifies code rely on useWithStale? (More consistently available with the possibility of corrupting code)

I imagine there are more of these issues where there is no obvious solution, with advantages and drawbacks for each available solution. Once more of these issues have been listed, for the consistency of the project, it would be beneficial for the team to lay out the project's chosen way of resolving these issues. This way, future features can have such decisions taken into consideration, and old code can be progressively refactored to adhere to such decisions.

[michaelpj]

I am at least planning to write some haddock for things at Zurihac and I'll cover the use* functions at least.