
Software is narrative - dhaneshnm
http://infiniteundo.com/post/158336863413/software-as-narrative-1n
======
ajarmst
I think I'll open with a dubious metaphor I just came up with and a demand
that the reader immediately and wholeheartedly accept that metaphor as literal
truth. That's how you grab an audience!

~~~
Textarcana
Yes, I write intentionally click-baity blog posts. You got me.

~~~
adrianratnapala
ajarmst's point goes beyond click-baitiness -- indeed it is about the little
quote-box on the first para rather than the title. You say: _" Any software
system begins as a shared narrative about a problem and the people who come
together around solving that problem."_

I can, in fact, bend my view of facts to fit this metaphor. And if am also
dubious about doing so, that's OK as it makes it all the more likely that I
will learn something new from your post.

So why spoil that with some the arrogant demand that: _" If you don’t accept
the above proposition completely then nothing I have to say about software is
going to work for you."_?

~~~
evincarofautumn
Just to advocate for the devil here, I think some advice is predicated on a
shared model, between the giver and the taker, of how things work. If you
don’t buy the model, then you probably won’t deeply understand or agree with
the arguments that would get you from the model to the thesis.

~~~
noshbrinken
I definitely appreciated this early warning to get off the ride.

~~~
Textarcana
While I appreciate the spirit of what you are saying, the average time on page
of 3 minutes 45 seconds (across 2k uniques) indicates most visitors are
continuing past the paragraph you claim would be problematic.

~~~
swsieber
Devils advocate: Do you know what the average time is to read the entire thing
is? If it's 7.5 minutes, then one possible explanation is that your audience
is split (50/50). Median time would be a much better indicator.

------
dannyrosen
The contrast here is great.

Finding the problem and creating a solution along with focusing on the process
of creating that solution in order to reduce risk of building the wrong
solution. Contrasted to building a solution along with a sane dev and
production environment for that solution to fit in, to increase possible
iteration velocity by reducing deployment inertia.

------
yodon
I think the OP is on a path that will eventually lead them to discover or re-
invent Conway's Law[0]

[0][https://en.wikipedia.org/wiki/Conway's_law](https://en.wikipedia.org/wiki/Conway's_law)

~~~
sebastianconcpt
Nice one! Thanks for sharing the insight

------
ldng
Just wondering if I'm the only one, but I like my logs to be the narrative of
what's happening in the system.

~~~
wickawic
Agreed. I think many people do a good job of logging when something goes
wrong, and maybe they are good about logging inputs/outputs of a system, but I
think that logging important decisions often falls off the table. Ideally I
would like to take a request ID, grep the logs, and get an entire story of
what happened to that request. In reality, this rarely happens!

~~~
fragmede
_> take a request ID, grep the logs, and get an entire story of what happened
to that request. In reality, this rarely happens!_

If that's the situation you find yourself in, I cannot praise centralized
logging with a good frontend highly enough because I frequently find myself
trying to figure out what happened to a request, and it's like night and day.

Needing to ssh anywhere and run grep against log files is functional if
there's only one or a handful of VMs, but it gets complicated with a handful
of machines, and even just SCP-ing the logs off becomes time consuming if
there are a lot of machines. Then once the logs are off, 'grep' quickly
becomes inadequate. (And I should know, I've built some truly horrible regexps
to try and grep for dates because I didn't know any better.)

All that friction means that answering the original question; figuring out a
detailed internal reason for why my customer received a 500 http status
response error, is just too toilsome for all but the most (as you noted)
doesn't happen in .

With centralized logging, I'm able to search for a request ID and see the
logs, and this is a reality as often as I need, in order to debug complex
multi-system issues.

~~~
girvo
Word of advice: the 'jq' tool for handling JSON files (couple with a glob like
'*.log' or something fancier with xargs or parallel) will absolutely save your
bacon in those situations. It's way more powerful than it appears on the
surface.

We had a series of Docker json-file driver log files. It's done as a raw list
(no array around it) of JSON objects -- which is a bit annoying to sort and
filter based on properties of the objects.

'jq '[inputs]' (asterisk).log > combined.json' was my favourite command today;
it combines all the files inputs and wraps them in an array correctly. No awk
needed!

Combine that with its cute:

jq '.someProp as $var | test("some search"; "gi") as $r | if $r then ($var +
$__loc__) else null end' (asterisk).log | grep -v "^null$" > filtered.json

And you're away to the races. Can then load the file directly in and
group_by(.somePath) and it will all magically work!

Edit: had to remove the actual asterix symbols as they screw with formatting
but are used for globbing the file names. Replace with the real character

------
d--b
Sorry I just don't understand the article. Can anyone rephrase?

~~~
nsuser3
The main point of the article appears to be:

> You always have to design both “the product” your customers want and “the
> environment” in which your product will run in production. Thus any software
> product begins with two obvious categories of “work to be done.” People
> ignore this because it seems [counterintuitive.][going_there]

~~~
Textarcana
Hey you saved everyone a click!

I am the author of the post and I approve this summary :)

~~~
marcosdumay
Your blog archive (where the title links to) seems to be broken.

~~~
Textarcana
Weird it just worked fine for me. [http://infiniteundo.com/archive/filter-
by/text](http://infiniteundo.com/archive/filter-by/text)

~~~
marcosdumay
Oh, don't mind. My network connection was the one that had a problem.

------
sebastianconcpt
This is a good metanarrative for software authors. The more the product wants
to be art, the more important this concept is. Humans are wired to spread
stories so if a product doesn't communicate plenty of good ones, then there
you have the anwer to why marketing budget isn't fixing the business.

------
b0rsuk
Okay, I'll take it at face value. Can you name a few competent programmers who
are also competent book / story writers ?

~~~
nickjj
I create video training courses on tech topics and one of the metrics I use to
determine "is this performing well?" is the completion rate of the courses and
individual videos.

I started taking communication and story telling pretty seriously about 9
months ago and the data on my 2 latest courses (where I tried to create a
cohesive narrative of the content) shows the completion rate being quite a bit
higher than my older courses.

Are there other things at play? Maybe, but I'm 100% convinced it takes more
than "raw programming talent" to be a good programmer in general.

When it comes to designing library code or public APIs, I would rather use
code written by someone with 5 years of writing / story telling experience and
2 years of coding experience vs someone with 10 years of coding experience but
can't communicate well at all.

Chances are the 2nd person wouldn't be able to see the "big picture" stuff
when it comes to designing APIs, and when it comes to API design, the big
picture is the most important thing. The implementation details of each
function is the easy stuff (since you're a Google search away from solving
most technical problems).

There's also many other factors that matter besides your code. For instance,
if I can't even find your project, or your documentation is lack luster then
it doesn't matter if you wrote the most elegant code in the universe, I'm not
going to use it.

