Improve RecentEra docs (#4296)

Related Advice Process Decision:
https://docs.google.com/document/d/1xazQNECWex3GWp2-yzAeJGnYvAHchamgNVvFDs3ydcg/edit?tab=t.0#heading=h.gjdgxs

lib/balance-tx/lib/internal/Internal/Cardano/Write/Eras.hs

@@ -110,13 +110,48 @@ type LatestLedgerEra = Conway
 -- RecentEra
 --------------------------------------------------------------------------------
 
--- | 'RecentEra' respresents the eras we care about constructing transactions
--- for.
+-- | We define the term "recent era" to mean one of the /two most recent eras/.
+-- This represents eras we care constructing transactions for.
+--
+-- === Why /two/ eras?
 --
 -- To have the same software constructing transactions just before and just
--- after a hard-fork, we need to, at that time, support the two latest eras. We
--- could get away with just supporting one era at other times, but for
--- simplicity we stick with always supporting the two latest eras for now.
+-- after a hard-fork, we need to, for a time, support two eras.
+--
+-- === 'RecentEra' the value vs 'IsRecentEra' the class
+--
+-- We keep track of the era on the type-level, and our code is mostly
+-- polymorphic in the era. In order to simplify such code, we impose the
+-- following two guidelines:
+--
+-- 1. For any type declaration that mentions the era type parameter, you SHOULD
+-- add a type class constraint IsRecentEra era. (Think of this step as adding a
+-- type signature 'era : IsRecent'.)
+--
+-- 2. For any declaration that depends on era, but does not mention era in the
+-- type, you SHOULD add a value-level argument of type RecentEra era in order
+-- to disambiguate the type and AVOID the use of AllowAmbiguousTypes. (In old
+-- Haskell code, the Proxy type was often used for this purpose.) In most other
+-- cases, you SHOULD NOT add a value-level argument.
+--
+-- DO:
+--
+-- @@
+-- isBabbageOnwards   :: IsRecentEra era => BabbageEraOnwards (CardanoApiEra era)
+-- signTxByAlice      :: IsRecentEra era => Tx era -> Tx era
+-- makeAndSerializeTx :: IsRecentEra era => RecentEra era -> Intent -> ByteString
+-- @@
+--
+-- DON'T:
+--
+-- @@
+--    -- The type class constraint is necessary
+-- isBabbageOnwards   :: RecentEra era -> BabbageEraOnwards (CardanoApiEra era)
+--    -- The value-level argument is probaby superfluous
+-- signTxByAlice      :: IsRecentEra era => RecentEra era -> Tx era -> Tx era
+--    -- This type is ambiguous
+-- makeAndSerializeTx :: IsRecentEra era => Intent -> ByteString
+-- @@
 data RecentEra era where
     RecentEraBabbage :: RecentEra Babbage
     RecentEraConway :: RecentEra Conway
@@ -130,6 +165,7 @@ instance TestEquality RecentEra where
     testEquality RecentEraBabbage RecentEraConway = Nothing
     testEquality RecentEraConway RecentEraBabbage = Nothing
 
+-- | C.f. 'RecentEra'
 class
     ( CardanoApi.IsShelleyBasedEra (CardanoApiEra era)
     , CardanoApi.ShelleyLedgerEra (CardanoApiEra era) ~ era