A problem with hiding complexity, or why it might not be so bad to say "this is a monad"

[Matt Wetmore]

I've been spending a few weeks getting into Elm after spending some time with Haskell, and really enjoying it. I really enjoy working with Haskell, and for many of the same reasons I've had a lot of fun with Elm as well. However, I have some thoughts about the language which put me on the opposite side of the party line.

I understand that one major goal of Elm, which manifests in the language design, documentation, and general discussion, is making the language as accessible as possible to programmers without any FP experience. I sympathize with this goal, and support it. However, I think certain decisions which are made in the pursuit of this goal are a little short-sighted. One example - I don't think it's such a bad thing to talk about unifying concepts such as functors or monads.

For example, we have a number of type constructors which are monads, but seem to carefully avoid telling anyone this. I understand that monads are intimidating, but if you know what they are you have a big advantage over the Elm programmer who doesn't. Since the Elm community is big on concrete examples, here is one: I've been working on a package for handling keyboard shortcuts in Elm, and part of this project involved writing a parser for strings like "shift+r" or "up up down down left right left right b a enter". Since parsing may fail, this is a natural use case for Result. Anyone with a little bit of Haskell experience will note that Result (with some constant error type, say, String) is a monad: "return" is "Ok" and ">>=" is "andThen". I've been working with the following alias:

type alias Outcome a = Result String a

Now to parse something like "shift+r", I split on "+" and parse each atom. Parsing an atom may fail; I want parsing the entire expression to fail and report the relevant error message if this happens. So, what I want it something with type "List (Outcome a) -> Outcome (List a)". Because I've done some Haskell, and Outcome is a monad, I know I can just use sequence. So that's what I did, (literally copied from a Haskell implementation I found online) and I got exactly what I wanted. But had I never known about these things, then I have to write 

Programming guided by types is a great thing - it is very nice to look at the type signature for something you need and know to use some function based on that alone. In Elm, if I need any of the following:

List (Maybe a) -> Maybe (List a)

List (r -> a) -> r -> (List a)
List (Task x a) -> Task x (List a)

then I'm probably looking for a sequence function. At least Task has it defined. If I know what a monad is, and I know that these are monads, then I know I can write a sequence function and it will always be done in the same way (in _my_ ideal world, there would be typeclasses too which basically do this for me once I define "return" and ">>=", but I know that is far off/may not happen). If there is some indication in Elm documentation or something that these are monads, I can reason more effectively based on types. Sequence is not the only function I get "for free" either; I get all of these too.

This is running a bit long so I'll wrap it up - I think we should at least talk about monads, functors, etc with respect to Elm, even if it's in some section on "advanced topics". It seems awfully short-sighted of us to ignore a wealth of advancement in functional programming which is relevant in Elm just because some words seem scary. I'm not saying it has to be the first thing a newcomer to Elm sees, but I think these concepts are very important if one wants to become a good Elm programmer. Otherwise we're asking people to reinvent the wheel.

[Max Goldstein]

Firstly, thanks for writing in a reasoned tone rather than an ideological one. Now, a few points:

I think names like "monad" and "functor" are going to be confusing to people, and so far the approach taken has been to talk about the operations (verbs) rather than the class (noun). For example, "tasks support andThen" rather than "tasks are monads".

With regards to your Outcome example, have you seen Json.Decode? It works almost exactly the same way. I think the most compelling argument is that we're wasting time and duplicating code when we have constructs like Json.Decoder a and Outcome a that are very similar, but we can't share operations like sequence and oneOf. Instead we have to manually reimplement these operations, and ensure that they are all present and named the same whenever we write another library that happens to be a monad.

However, I disagree with the notion that stating "this module is a monad" will be helpful to programmers. If you come from Haskell and are familiar with its type classes, you can typically recognize them by their type signature. It's also not too hard to learn that andThen is bind, map is fmap, applicative functors are... well, really mapN, and (~) for signals. Elm has three pseudo-type-classes (I'm not sure if there's an official name), appendable (monoid, supports (++)), comparable, and number. You can't define more of these, or define a new type to comply with them (comparables work inductively though). This system is a bit like eqtypes from Standard ML, but equate-ability is not checked at compile time, and you can get a runtime error if you equate signals or functions. Another problem is that Dicts and Sets do not support semantic equality because they're union types (ADTs) underneath, and it equates structure not content. -- So yeah, the system isn't perfect, and we're open to opinions on how to improve as Elm matures.

I hope you like Elm and stick around, but if you want something closer to Haskell, you can also try ghcJS and PureScript.

[BethAr]

The problem of inventing a new terminology is that it puts a lot of burden on Elm's documentation. If you say something is a "functor", I can rely on documentation from other languages to understand it, if you call it anything else I will only recognize it as a "functor" if I already know what it is.

In the end I believe you will make people completely dependent on Elm specific documentation, whereas, if you used common terminology, people could rely on other sources. 

My learning of Elm has been difficult. Reading through the mailing list, I do feel very alienated as a Haskell user.

[Richard Feldman]

I really appreciate your perspective on this, and particularly the effort to contextualize it in terms of the Elm community's values. Nicely done! :D

I do disagree with the conclusion, though. Consider...

In Haskell:

- Learning curve is a major known problem. The top two autocompletes for "why is haskell" are "why is haskell lazy" and "why is haskell so hard to learn" - so it's reasonable to be wary of having Elm introduce complex Haskell concepts even under the banner of "advanced users only."

- As a result of how empirically difficult Monads are to explain, there has been a comical proliferation of tutorials about them - to such a degree that it is literally a running joke. One might reasonably conclude from all this that Monads are the biggest contributor to Haskell's major learning curve problem.

- Even assuming there is a net time savings to be had once everyone on a team understands an abstraction, it's disingenuous to consider only the hours saved once the abstraction has been learned—without factoring the hours expended to learn it in the first place. Maybe some people find these concepts fun and are motivated to learn them for their own sake, but for those of us trying to convince our JavaScript peers that our team would be better off with a functional language, the cost/benefit analysis on the time investment required to become productive is a huge deal.

- Building on top of abstractions like Monad and Applicative leads naturally to other, even more complex abstractions like Monad Transformers. As Evan put it in another thread, it took him years to understand Monad Transformers, and he is a highly accomplished programmer coming from a strong functional background. Given that the entire point of higher-level languages is to save human programmers time, that goes beyond troublesome: that is an outright failure as a higher-level programming language.

In Elm:

- You sometimes have to copy/paste a bit more boilerplate

To me, Elm is clearly taking the right approach here.

One other note: please remember that there's a huge survivorship bias among Haskell programmers. Every time I tell non-Haskellers that they won't have to learn Monads to get into Elm, they show noticeable signs of relief and get more interested. I don't think the incremental code reuse benefits outweigh that, and especially not at this stage in Elm's development.

Quite the opposite. :)

[Matt Wetmore]

Thanks for not tearing me apart guys, I was afraid that y'all might be tired of yet another "why isn't elm more like haskell" thread.

Here are a few responses: 

Max:

I think names like "monad" and "functor" are going to be confusing to people, and so far the approach taken has been to talk about the operations (verbs) rather than the class (noun). For example, "tasks support andThen" rather than "tasks are monads".

This is fair. I'm tempted to pull out the old "OOP languages have their own terminology, and people get used to that" card, but you're right - the terminology is off-putting to some. My main worry with this approach, however, is that language such as "andThen" doesn't scale to all possible monad instances. But we can cross that bridge when we get there.

However, I disagree with the notion that stating "this module is a monad" will be helpful to programmers. If you come from Haskell and are familiar with its type classes, you can typically recognize them by their type signature

You're right. I think a better approach is to provide learning material about such things, such as "how to spot a monad", along with implementations of monad functions such as sequence or forM which you could copy-paste in when you know the associated return and bind for a given type - like in my example github link in the OP. I'm thinking about writing something like this, and if it works out it would be the sort of thing I'd like to see as an official learning resource (not necessarily my version, just something in this spirit). However, I'm afraid that insistence on avoiding language like "monad" would prevent such resources from existing. Am I right to be afraid of this? If not, I'd be willing to help in this effort.

I hope you like Elm and stick around, but if you want something closer to Haskell, you can also try ghcJS and PureScript.

I don't want all of Haskell - I'd agree with you guys that it isn't all necessary for making good frontends. Elm is compelling to me for its first-class implementation of FRP and its focus around FRP. ghcJS and PureScript certainly have FRP implementations, but I would prefer to stick to a language which is designed around FRP. If there wasn't so much I _did_ like about Elm I would move to your alternatives, but I'd rather see Elm mature into a great, focused language than use those general-purpose alternatives. 

Richard:

Learning curve is a major known problem. The top two autocompletes for "why is haskell" are "why is haskell lazy" and "why is haskell so hard to learn" - so it's reasonable to be wary of having Elm introduce complex Haskell concepts even under the banner of "advanced users only."

I do not see how having these features under the banner of "advanced features only" would scare people off if they are not essential language features. You don't need to add it to "why use Elm" overviews. Elm stands on its own already for the reasons I stated in my response to Max. Honestly, the whole "it will scare people off" is a much less compelling argument than "it's not worth the effort to implement at this time". I'm not advocating that Elm build its identity around these features, only requesting that we acknowledge their existence.

Building on top of abstractions like Monad and Applicative leads naturally to other, even more complex abstractions like Monad Transformers. As Evan put it in another thread, it took him years to understand Monad Transformers, and he is a highly accomplished programmer coming from a strong functional background. 

This is a slippery-slope argument. Just because we talk about concepts like Monad and Applicative doesn't mean we _must_ talk about Monad Transformers, etc. Monads, etc have their own uses without talking about their more-complex cousins. 

You sometimes have to copy/paste a bit more boilerplate

Given that the goal is to attract more users to Elm, isn't it fair to argue that this is one thing which turns people _off_ of Elm? I've done my research, and there are a lot of threads advocating against this duplication. So clearly it's bothering people who want to use Elm.

 Every time I tell non-Haskellers that they won't have to learn Monads to get into Elm, they show noticeable signs of relief and get more interested.

I'm not trying to make it so you need to learn monads to use Elm. I'm just put off by how many big-name Elm users want to avoid mentioning them anywhere official, for fear of turning away newcomers. I don't think that offering learning materials for these things in the context of Elm will scare people away if we don't tout them as required.

[Dobes Vandermeer]

It seems to me that monad as a programming term has been ruined unintentionally by Haskell, which is part of why it is so hard for people to understand. 

(Tl;dr of the rest... These terms should be replaced because Haskell messed them up)

People say things like "the Maybe Monad" or "monads are for IO" and the imprecise language here can really muddle things up.  From a modeling perspective Maybe is not really a Monad, but you can easily make a Monad from it. 

In Haskell you can use Maybe as if it is a Monad, and they overload things using type classes so that it works, in a kind of magical way.

A Monad is a trio of functions/morphisms following certain rules.  Maybe, the type constructor, is the first function. In Haskell using a type class instance Maybe instances implicitly carry around the other two functions (return and bind). 

A less indirect way of building the monads would be to just define a data type with the three functions. But then some convenience would be lost... And I'm not sure Haskell even allows you to put a type constructor into a data type.

So the result is a lot confused people confused between the Haskell idea of monads and the formal definition of it that are fairly different.  The same goes for things like applicative, functor, and so on.  The Haskell version is encoded into type classes as a kind of approximation of the original concept, causing mayhem for beginners.

This, I do think we may need new terms for these things because of their confusing usage in the programming world up to now.

--
You received this message because you are subscribed to the Google Groups "Elm Discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elm-discuss...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Aaron VonderHaar]

After writing avh4/elm-transducers a few weeks ago, I am led to suspect that monads can probably be implemented in current Elm by making clever use of records with the only downside being that it might become painful for users of monads to write type annotations for their code.  (And the upside being that it will probably expose some more obscure bugs in elm-compiler.)  I'd suggest someone try writing an elm-monads package and then maybe we could discuss the merits of such an API more directly.

[Richard Feldman]

 

Learning curve is a major known problem. The top two autocompletes for "why is haskell" are "why is haskell lazy" and "why is haskell so hard to learn" - so it's reasonable to be wary of having Elm introduce complex Haskell concepts even under the banner of "advanced users only."

I do not see how having these features under the banner of "advanced features only" would scare people off if they are not essential language features. You don't need to add it to "why use Elm" overviews. Elm stands on its own already for the reasons I stated in my response to Max. Honestly, the whole "it will scare people off" is a much less compelling argument than "it's not worth the effort to implement at this time". I'm not advocating that Elm build its identity around these features, only requesting that we acknowledge their existence.

I hear you, but really that's pretty much what the status quo is. :) Nobody's denying that monads exist, or claiming `Task` isn't monadic. But if we acknowledge it and then move on to other things, rather than pressing on down that road, we can keep the focus on what we do want to be the foundation of the language. :)

 

Building on top of abstractions like Monad and Applicative leads naturally to other, even more complex abstractions like Monad Transformers. As Evan put it in another thread, it took him years to understand Monad Transformers, and he is a highly accomplished programmer coming from a strong functional background. 

This is a slippery-slope argument. Just because we talk about concepts like Monad and Applicative doesn't mean we _must_ talk about Monad Transformers, etc. Monads, etc have their own uses without talking about their more-complex cousins. 

True, but the alternative is encouraging people to look for fresh abstractions using Elm's unique set of rules. Consider that Monadic I/O itself was discovered because Haskell prohibited side effects. At first this made doing I/O difficult, but then a better way emerged...out of the necessity of trying to accomplish things without the usual tool of side effects to work with.

What abstractions do people come up with to reuse code in an environment with 100% type inference, 100% immutability, and no side effects anywhere? We know the answer when you have typeclasses, but what if you don't? Who says we don't end up finding a way to get the benefits without the drawbacks?

I am genuinely curious to find out, and I think the best way to foster that is to encourage going back to the drawing board rather than trying to see how abstractions that work best in an environment with typeclasses can be imported into one without them.

You sometimes have to copy/paste a bit more boilerplate

Given that the goal is to attract more users to Elm, isn't it fair to argue that this is one thing which turns people _off_ of Elm? I've done my research, and there are a lot of threads advocating against this duplication. So clearly it's bothering people who want to use Elm.

This is true, but it's also true that no purely functional language has ever escaped niche status. I think it's reasonable to say that catering to the existing niche over the broader potential audience (and I do believe the two are mutually exclusive in this particular case) is unlikely to change that. :)

Anyway, thanks for another well-said response. Hopefully this clarifies my thoughts on the subject!

[Brian Slesinsky]

On Tuesday, June 9, 2015 at 4:12:07 PM UTC-7, BethAr wrote:

The problem of inventing a new terminology is that it puts a lot of burden on Elm's documentation. If you say something is a "functor", I can rely on documentation from other languages to understand it, if you call it anything else I will only recognize it as a "functor" if I already know what it is.

It seems like this could be solved if someone were to write an introduction to Elm for Haskell programmers? Then it would certainly be fair game to use Haskell terms. In general, though, it seems better to make the weaker assumption that the reader has programmed in some programming language before, but not necessarily a functional one.

- Brian

[BethAr]

There seems to be an assumption that a Haskell programmer is always an advanced programmer, with experience in C, Javascript and what not. When I heard about Elm, I thought it was supposed to help functional programmers write front-end code using FRP principles. But after reading the mailing list, it seems its focus is at helping javascript programmers write better javascript.

I'm completely terrified of javascript and most imperative programming languages. Please remember, when you talk about beginners, that they are at both sides of the fence.

[Richard Feldman]

That's a totally fair perspective, but keep in mind that Elm is a far cry from the thing you want to avoid (JavaScript), and much closer to a thing JavaScript folks generally want to avoid (monads).

Correct me if I'm wrong, but I expect as a functional programmer you wouldn't be afraid of Elm devolving into imperative JavaScript just because we avoid discussing monads! :)

Conversely, if I were an imperative JS programmer (as I once was) and came across a FP language community pitching monads (even if clearly pitched as optional), I can't help but think this is going to be a harsher learning curve than something like Clojure where these notoriously complicated concepts are seemingly nowhere to be found.

[Max Goldstein]

Conversely, if I were an imperative JS programmer (as I once was) and came across a FP language community pitching monads (even if clearly pitched as optional)

The other problem is that optional features, aren't. React.js says their JSX syntax  is optional, but I have yet to see a React project that doesn't use it. And now many programmers are writing HTML in the .js files. I guess that's the other reason why it took hold - it was closer to the HTML being generated, an abstraction these folks were familiar with.

I think the point about creating resources for how to recognize common patterns is fair. For someone who has only worked with C-like languages, even type annotations will be strange. Also, if we don't ensure that Elm users all recognize the "andThen pattern", then they may create a function with the same annotation (or flipped) with a different name in a 3rd party library, which will make things much more confusing. These tutorials would also be a good place to indicate the other functions that go with these patterns ("if you write andThen, consider writing sequence like so..."). As for the absence of the term "monad", it may make them harder to find (we'll link to them, no big deal) but it will make readers more likely to get through the document.

[Brian Slesinsky]

On Wednesday, June 10, 2015 at 6:24:50 AM UTC-7, Max Goldstein wrote:

Conversely, if I were an imperative JS programmer (as I once was) and came across a FP language community pitching monads (even if clearly pitched as optional)

The other problem is that optional features, aren't. React.js says their JSX syntax  is optional, but I have yet to see a React project that doesn't use it. And now many programmers are writing HTML in the .js files. I guess that's the other reason why it took hold - it was closer to the HTML being generated, an abstraction these folks were familiar with.

I agree on the general point that optional language features can't easily be avoided because you need to be able to read other people's code. But regarding the specific example, I think it's important not to be misled by surface syntax: JSX is not really HTML. It's syntactic sugar for JavaScript function calls that create certain kinds of objects. In particular, a JSX attribute can contain an arbitrary JavaScript object, much like a parameter to a regular function call and unlike HTML where it can only be a string. Being able to construct view nodes anywhere in your program is a more flexible approach than using an external template language where everything you put into a template needs to be converted to HTML.

- Brian

[BethAr]

I insist on the point about documentation. When you call a "functor" something else, you better have a very good documentation of what that something else is, because you have simply precluded me from studying in other documentations (or even Wikipedia). This places a lot of burden in documentation, which I think Elm, so far, failed to meet. 

Not only I have to learn the basic concepts of web development, which are assumed in the documentation, but the knowledge I do have, and could be useful is obfuscated.

Brian Slesinsky made a good suggestion, most of this problem would be solved if there was a section addressing people coming from Haskell or other FP language. I noticed this mail:

Simple "Elm for Javascript programmers" documment

Can't we have something similar for Haskell? Where the main concepts are explained with the terminology we know?

[Matt Wetmore]

There is this, but I agree that a more in-depth article would be helpful. Since I will be flying/in layover for most of this Friday, perhaps I'll take a crack at writing one, since I've been spending the past day or so reading a lot of discussions about the similarities and differences between Haskell and Elm.

[Max Goldstein]

I think it's important not to be misled by surface syntax: JSX is not really HTML. It's syntactic sugar for JavaScript function calls that create certain kinds of objects. In particular, a JSX attribute can contain an arbitrary JavaScript object, much like a parameter to a regular function call and unlike HTML where it can only be a string. Being able to construct view nodes anywhere in your program is a more flexible approach than using an external template language where everything you put into a template needs to be converted to HTML.

Yes, I had this discussion with someone at a JS meetup recently. I made a point of saying "JSX syntax" and not "JSX templates", but that caution went out the window for the pithy "writing HTML in the .js files".

And indeed, elm-html has the same advantage of "templating" in a semantic language rather than find-and-replace syntax.

[Evan Czaplicki]

I just wanted to gather up some of the relevant thoughts that got us to where we are today:

• designing terminology for expected users
• Unhelpful / distracting details
  
• precision in terminology, and when to use it in the first place
• language design as a 20 year process
• who are the docs for?
  

I think one of the big takeaways here is that someone else has already run this experiment. Why would we do it again and expect different results?

A point I don't think I've made online is this: The amount of brain power lost in discussions about this stuff is crazy. Like my brain right now. Or yours. What if I was getting the 0.15.1 release ready now? Or improving tasks? Or tests? What if you were writing a library for data visualization or animation or calendars or so many useful things?! Richard is starting to use Elm at work, what if he had the time back from writing these emails?

The best argument is probably to just go talk to people with a different background than you and see what happens. Forget about what everyone on elm-discuss thinks, we are weirdos. What do other people think? What causes trouble? How can you communicate the important stuff clearly? This is what I do. I'll think of a bunch of ways to describe the same exact idea, and then try them all. The philosophy here certainly is guided by my gut, but I check that against reality to see what really works!

--

[BethAr]

A point I don't think I've made online is this: The amount of brain power lost in discussions about this stuff is crazy. Like my brain right now. Or yours. What if I was getting the 0.15.1 release ready now? Or improving tasks? Or tests? What if you were writing a library for data visualization or animation or calendars or so many useful things?! Richard is starting to use Elm at work, what if he had the time back from writing these emails?

I joined this community because I thought it was a community, not because I expected the language developers to step in and answer every question, this is what a community provides. If you or anyone else is doing anything important, you shouldn't be posting. I find it a little bit disturbing that you consider your personal obligation to waste time in discussions you find irrelevant. Other people, however, don't find it irrelevant, including myself. I must select a front-end platform for our next project and I would like to know what type of support I can expect, knowing only Haskell and nothing else.

I also do many useful things in my work, but I've stopped in order to learn your language, please don't chastise me for trying.

[Evan Czaplicki]

Sorry, I was just trying to fill in my perspective in a helpful way!

I'm part of the community too, and this is a topic I think about quite a lot, as the posts I linked to demonstrate :)

In any case, sorry again, I'll stay out of it. It seems like the "Elm for Haskellers" route is viable, but I wanted to give background info so that such a document would potentially clarify / summarizes the reasons behind the design choices.

--

[BethAr]

I apologize for my reply as well. I just felt a bit disheartened reading through the mailing list. Elm news are posted frequently in Haskell's community channels, so I expected Haskell users to be at least a target of the platform.

Thank you for making this project, by the way.

[Matt Wetmore]

Thank you everybody for humoring me on this, I've appreciated the discussion.

Evan, I've read (most) of the threads you've linked already. That's what I meant when I said I've done my research. As for your candid thoughts on these discussion, BethAr's reply describes the feeling I had reading it - I've spent a fair amount of time myself learning Elm, and to be honest it's disappointing that you believe these things aren't worth talking about. I gave a concrete example of why I think we should mention monads somewhere - this is based in my experience learning the language, not ideology. 

Frankly, I think some of the replies in this thread are missing my point. This may be my fault, and I don't hold any resentment over this. I think Max's reply this morning is a very fair representation of what I want to see - I'll quote it here for convenience:

I think the point about creating resources for how to recognize common patterns is fair. For someone who has only worked with C-like languages, even type annotations will be strange. Also, if we don't ensure that Elm users all recognize the "andThen pattern", then they may create a function with the same annotation (or flipped) with a different name in a 3rd party library, which will make things much more confusing. These tutorials would also be a good place to indicate the other functions that go with these patterns ("if you write andThen, consider writing sequence like so..."). As for the absence of the term "monad", it may make them harder to find (we'll link to them, no big deal) but it will make readers more likely to get through the document.

I have some quibbles with his last sentence (I think that advantages of seeing things in their correct context outweigh the disadvantages of a slightly more complex document. Perhaps monads could be mentioned in a footnote only?) but that's ok.

To use your example, I'm not advocating we say "to add numbers you must use the addition group". I'm saying that we should note somewhere that "numbers, along with this addition operation, forms a group". Sure, this is new terminology, but it is _helpful_. There is a reason we study groups, and it isn't just intellectual masturbation. They give us a broader perspective on what we are working with. In the same vein, I believe that if we mention somewhere that hey, Result or Maybe or whatnot is a monad (in the Haskell sense), and perhaps link to a discussion of the things you can do with monads (sequence them, for example), we are helping people. 

As I said, I would be willing to help with such efforts, because I have a personal interest in pedagogy. One reason I want to stick with Elm is because of the efforts you've made to keep the language consistent and welcoming to newcomers. But I think focusing purely on what makes the language non-intimidating is shortsighted if it means discussion of higher-level concepts somewhere is verboten. And frankly, your response makes me less willing to contribute to the community since these discussions are apparently just a waste of time. I can imagine seeing this monad stuff come up again is tiresome, but I think the approach I'm advocating is a bit different from the previous ones (it's an experiment that hasn't been run, to use your terminology) and merits more than just "why are we doing this again". 

[Evan Czaplicki]

Thanks for that, that helps me get it more. I think pointing out that andThen is a somewhat common pattern makes sense.

I've been meaning to write up an "error handling in Elm" document that goes into how Maybe and Result work. That would certainly touch on map and andThen and such. The existing task stuff gets into this a bit already, but I think a "this is how we do error handling" document might align with what you are suggesting?

--