Why I do not doc quirks of a characteristic on the characteristic itself.

Each product supervisor is aware of this example:

• A person works with characteristic X1.
• They discover a limitation / bug / quirk and need to work round it.
• The right workaround or different is characteristic X2, however with out understanding that X2 exists, the person doesn’t discover it and spends quite a lot of time in search of it.
• The person requests X2 be documented on X1, as a result of that may have saved them a ton of time.

That is such a standard sample, and whereas it’s completely comprehensible for such a person to request this, it’s so terribly mistaken to provide in to this person’s request. Why is it mistaken?

The options are unrelated

More often than not, the 2 options X1 and X2 are unrelated and simply “occur” to be linked on this particular person’s state of affairs. Let’s take jOOQ, for instance. Think about you’re employed with the SUM(X) mixture operate. For historic causes, this operate (like many different arithmetic capabilities) returns BigDecimal in jOOQ, so it received’t overflow, regardless of the enter sort. The signature of the operate is:

public static AggregateFunction<BigDecimal> sum(
    Subject<? extends Quantity> area
) { ... }

This may increasingly or will not be a superb factor. In spite of everything, individuals are used to generics in jOOQ’s API, so they might have most well-liked this signature as a substitute (which dangers overflowing for varieties like TINYINT / Byte):

public static <T extends Quantity> AggregateFunction<T> sum(
    Subject<T> area
) { ... }

So, characteristic X1 is SUM(X). The “quirk” is that it could return an surprising sort. (The quirk is controversial. The related subject to handle this isn’t very talked-about, so it could simply as nicely be tremendous).

Now, for some customers preferring the choice signature, characteristic X2 is the coerce() operate, a jOOQ operate that works like a SQL forged(), however doesn’t affect generated SQL. It’s applied totally within the consumer. Although, forged() would additionally work right here.

For instance, to get an Integer sum:

// As an alternative of:
Record1<BigDecimal> r1 = ctx
    .choose(sum(TABLE.COLUMN))
    .from(TABLE)
    .fetchOne();

// Get this (the place SQLDataType.INTEGER is used):
Record1<Integer> r2 = ctx
    .choose(sum(TABLE.COLUMN).coerce(INTEGER))
    .from(TABLE)
    .fetchOne();    

coerce() is such a helpful characteristic X2 in jOOQ, it’s in all probability price understanding about it when you’re a jOOQ energy person. It isn’t associated to X1 (the SUM(X) mixture operate), though it helps work round a “downside” (or quirk / historic API design alternative / and so on.) that’s particular to SUM(X) (and dozens of different arithmetic capabilities).

The characteristic is unknown

However the issue a person might need is that this:

• Customers haven’t any downside discovering SUM(X), the X1. Each supported SQL operate has a corresponding jOOQ methodology in DSL, and jOOQ customers are rapidly skilled to look there for something they already know from SQL.
• Customers do have an issue discovering out learn how to coerce() or forged() an information sort, first as a result of 1) they might not know (or have forgotten, or are unable to attach) the idea, and a couple of) it’s merely not associated to the person’s activity at hand.

So, quite a lot of time could also be spent in search of an answer. With out understanding what the very best answer is, alternate options could also be explored. Within the worst case, these alternate options additionally trigger (unrelated!) points, and the much more irritating XY downside ensues.

Even with out the XY downside, quite a lot of time could also be wasted in search of the answer X2.

The urge to doc

If the person finally finds out about X2 (the coerce() operate), they may request that X2 be documented on X1, as a result of that may have actually helped them. And there’s little doubt that this type of documentation would have helped this specific person.

BUT!

Most customers who work with SUM(X) don’t must know something about coerce(). They’re completely proud of BigDecimal, or alternatively, they might have discovered a completely completely different strategy to turning BigDecimal into Integer (e.g. BigDecimal::intValue) and so they’re completely proud of their answer X3.

If X2 was documented on X1, for many customers, that may have simply been noise. Maybe it’s not horrible noise however:

• It’s a primary little bit of noise on X1 about an unrelated characteristic X2.
• The following person will discover X2 to be inadequate for his or her downside and would need to have X3 documented as nicely.
• The following person will discover a completely completely different limitation in X1 and can need to have their workaround X4 documented as nicely (for instance, the truth that SUM(X) returns NULL as a substitute of the id worth 0 for empty enter units, a standard SQL “quirk”).
• The following person may have a limitation on X5 and can need to have X1 and X6 documented there.

The set of options X = {X1, X2, ..., Xn} is massive, and if a product is designed nicely and has quite a lot of extremely reusable elements, like jOOQ, then in precept, nearly each characteristic can work together with each different characteristic.

That is already onerous sufficient to check, but when each mixture additionally must be documented together with a listing of quirks, caveats, gotchas, workarounds, and so on. then we’ll by no means cease documenting issues that 99% of customers won’t ever must know and thus understand as noise.

As an excessive instance: Think about a person who has to cross a Record<T> to methodology(Record<T>). However they’re unaware of ArrayList. Not solely do they request ArrayList be documented on methodology(), but in addition the truth that an ArrayList may be created utilizing new. It’s completely unrelated noise!

There could be a lot noise that our person who needed X2 (the coerce() operate) to be documented on X1 (the SUM(X) mixture operate) wouldn’t even discover this bit of knowledge within the limitless checklist of quirks. For sure that transferring that exact quirk to the highest of the checklist of quirk isn’t going to be the appropriate answer to discovering this bit of knowledge.

So, what’s one of the best ways to assist this person?

Personally, I like Stack Overflow. Folks understand the moderation as harsh, however the massive advantage of this moderation is that good questions are at all times very particular and thus helpful for the following person who finds the query on Google. It’s completely tremendous to ask in regards to the mixture of X1 and X2 on Stack Overflow. Whereas the options are unrelated, the mix does assist this specific person. So if this person asks:

I need to use X1, however I bumped into this quirk. How can I work round it?

Then I may reply:

Use X2 as a workaround. Right here’s how: [ … ]

That is a lot a lot better than documentation on the Javadoc or within the handbook:

• It doesn’t generate noise. 99% of jOOQ customers aren’t involved with this Q&A, so they are going to by no means Google it, and thus by no means encounter this query. So, they’re completely satisfied.
• It’s extremely particular. The 1% of jOOQ customers who do have the identical query will discover this reply on Stack Overflow (or ChatGPT & co, which plagiarise Stack Overflow), in order that they’re completely satisfied as nicely.

Conclusion

Documenting quirks is a slippery slope. As a product grows and matures, it accumulates quirks. There are not any exceptions to this. Documenting all of those quirks someplace is essential, as a result of customers who run into them will need solutions.

Documenting these quirks on the characteristic documentation itself isn’t the appropriate alternative, nonetheless, as a result of most customers received’t be involved with the quirk. The checklist of documented quirks will rapidly turn out to be overwhelming.

A Q&A of some type is often the very best strategy, be it:

• A query on Stack Overflow
• A problem on a difficulty tracker with a associated dialogue in regards to the quirk and all of the potential workarounds