Regarding "The Harrowing Search for the Elusive Technical Answer"

This is a reply to Corey Quinns blog post. I think this is more generally useful however, therefore this article. I am going to assume you don't have time to read the original post, summary follows.

Corey (like me) encounters seemingly absurd technical problems from time to time. Which he describes as starting this way:

1. Encounter technical problem.
2. Search in vain for an answer.
3. Lose all hope.

In this particular case it was setting HSTS headers in "AWS API Gateway v2", a service which is unsearchably named "HTTP APIs".

The solution Corey eventually came upon is that the AWS Service in question just forwards any (?) header that is in the response object.

Coreys 5 step pattern for developer harrowing

1. Encounter technical problem.
2. Search in vain for an answer.
3. Lose all hope.
4. Eventually discover an answer.
5. Don’t bother to publish the answer for the next sucker

Preventing this is Coreys stated problem.

Reply

I have personally experienced this many times, but it seems that the time spent in "Lose all hope" is decreasing as I get more experience with time. Most recently an Elasticsearch "problem" due where the solution was documented in the Quickstart, and Only in there.

There are many angles you can come at this from, I will write about 2.

Name your projects cutesy things

This is the title of a ntietz blog that discusses the age-old question of naming projects descriptively vs cutesy. The relevance of that post in our case is that if AWS had named their "API gateway v2" a cute name instead of descriptively it would be easier to filter out a lot of noise, when looking for specific information about it.

There are in fact 2 "sins" of AWS here:

1. Naming a service "API Gateway"
2. Naming the followup the same except with "v2" slapped on

These are hard to search for, and filtering which "version" the information you're reading is about, particularly in Q&A type sites is even worse. (Why would you specify "v1" if there's no "v2" at the time of writing?) Further, in my experience there can be big enough difference between AWS service versions that it is essentially unrecognizable on the technical level. When that is the case, it is extraordinarily annoying to get search hits for something that is very different to your query. Even worse if some parts are in fact the same and the same information applies to both "versions", because then helpful people will point out that they behave the same (or so they think).

So, name your frameworks/services cutesy things, that are searchable at least in its context (such as "AWS").

Generic solutions to specific problems

Or: How to think (stupid) like a software engineer

The normal pattern to searching for a technical solution is to make your query as specific as possible with the correct wording. The next most common is probably asking a friend or two. If you're still stuck I find that stepping back to the more general case tend to yield results, as it was in my case, I should have gone back to basics (Looking at quickstart). Instead I found the quickstart through a GitHub code search, which found the PR that changed the Quickstart. This also matches Coreys case, where the solution was more related to "How does AWS API Gateway handle headers in the response" rather than "How to set the HSTS header statically in API Gateway".

Software engineers (including me) seem to have a deep desire, at times disease like, to make a system that solves for every case. This generally works well for frameworks and libraries, due to the designer not knowing how it will be used. However, this also makes them hard to use, because there are very few specific answers, instead you have to understand the library or framework in general to answer any specific questions.

I believe this is also the reason why StackOverflow is so successful, it fills the need of specific questions and answers, and is reasonably searchable (or at least a community that tries to make it searchable).

Mitigations

I think we have 3 mitigations for Corey's problem

1. Make your framework/library/service names searchable
2. Think like a (too clever) engineer, look more generally instead of more specifically. Perhaps even asking "How would I design for this case, if I also had to solve for all other constraints I know of?"
   • This can be alleviated somewhat by good API design and excellent documentation for the same, clearly showing the constraints of the system and how it interacts (or not) with payloads.
3. Ask a question publically on StackOverflow or similar. This solves for future people with similar question (if there is an answer). It does not solve (as I've sometimes been told) the base problem if lacking documentation or poor API design however.