11 ms·

This struck a chord with me: "Software Is about Developing Knowledge More than Writing Code" I've experienced more issues caused by management passing around t

This struck a chord with me: "Software Is about Developing Knowledge More than Writing Code" I've experienced more issues caused by management passing around tasks between teams and never paying attention to knowledge and knowledge transfer. What's amazing, is that in over 18 years as a software engineer, I've seen this so many times. Teams will function well, then the institution tries to change. Often they will try to open up the "innovation" by throwing money at R&D, basically trying to add bodies in order to grow. Then you have tons of teams, and communication becomes very challenging, so then they grow some kind of "task management" layer. Management that never understands who actually _knows_ something, just tracks how much "theoretical bandwidth" they have and a wishlist of features to create. And then the crapware really starts flowing. And then I get bored and move on to the next place.

civicsquid 7y ago
One of my professors condensed that point into something I thought was clever: "Software engineering is the distilling of ambiguity". I think about that whenever I get frustrated about a vague spec or lack of details. It's the job!
- onion2k 7y ago
  "Software engineering is the distilling of ambiguity" I hope he meant separating out the ambiguity rather than concentrating it. :)
  - hguant 7y ago
    I can see it working both ways - in many cases, I'd like my ambiguity distilled down to one specific point, while the rest of the project deals with lower specific ambiguity (where ambiguity in my mind is equal to "is this thing possible").
mmatants 7y ago
Apparently, Peter Naur (the N in BNF) wrote this up nicely back in 1985 in "Programming as Theory Building": http://pages.cs.wisc.edu/~remzi/Naur.pdf http://pages.cs.wisc.edu/~remzi/Naur.pdf
- sword_smith 7y ago
  I only have one year of formal CS education but that paper is one of my favorites on the topic. Naur is also the founder of CS at the University of Copenhagen, the place where I studied :)
- mcnichol 7y ago
  You should consider making this it's own article. "...the designers job is not to pass along "the design" but to pass along "the theories" driving the design. Knowledge of the theory is tacit in owning..." Well said. Thank you!
  - fsloth 7y ago
    I would prefer people read the original paper than any second-hand explanation of it. The paper is very readabale and understandable, and is probably relevant as long as into the future as human beings write code.
    - majewsky 7y ago
      When mcnichol said "make this its own article", they probably meant to submit the link to HN as its own submission, not to blog about it.
      - mcnichol 7y ago
        Yeah, that's what was meant. Totally agreed with the statement above this one, it reads well.
- fsloth 7y ago
  I was about to suggest the same thing. This paper should be mandatory reading for anyone that is professionally involved in a software development project.
clumsysmurf 7y ago
> "Software Is about Developing Knowledge More than Writing Code" The company I work for uses Scrum. They consider the User Stories + the code to be everything you need. I struggle with this, but my manager says they don't want to get tied up doing documentation "because it goes out of date". Beside, they are being Agile which "prefers working code over comprehensive documentation". I am wondering what other companies do to capture this "distilled knowledge". The backend services I rely on are undocumented beside some paltry swagger that leaves much to be desired. The front end has no product-level "spec", if you want to rebuild the thing from scratch. There isn't even a data dictionary, so everyone calls the same thing by different terms (in code, and conversation). There are just user stories (thousands) and code. Does anyone have any suggestions on how to fix this?
- gnaritas 7y ago
  Knowledge is captured in people, not code. The code is byproduct of the people, the people who are the asset.
- tannhaeuser 7y ago
  This is not necessarily in opposition to what TFA states: that programming is about knowledge engineering. It just happens that knowledge flows through user stories and code. This might work well or not so well for your team, and there's nothing to fix here. Managers should be aware, though, that this means you no longer have a project, but a line organization put up indefinitely, and where when the teams is disbanded, no "product" as such does remain; nor would it be possible to hand-over the "project" to an offshore team.
- PaulRobinson 7y ago
  "prefers working code over comprehensive documentation" does not mean "don't do documentation". Documentation is essential. How things work is an important thing to document. Ideally it should be in version control and be generated from the code, because then it's less likely to go out of date. It still has problems (What do you do when the code and the documentation disagree? Which is correct?), but they're not as severe as the problems that arise when there is no documentation at all. What is less useful is having comprehensive documentation for those things that are yet to exist. Writing a few hundred pages of specification and handing it over to the dev team is waterfall, and it is _this_ that the Agile manifesto signatories were interested in making clear. I'd fix it with strategic DDD - I'd develop at least a "ubiquitous language" (or a UL): I'd get others to work with me on having clear terminology and making sure that is used consistently both in user stories and in the code base. That's table stakes. I'd then event storm the contexts I'm working in and start to develop high level documentation. Even at this point relationships between systems emerge, and you get to draw circles around things and name them (domains, contexts), and the UL gets a bit better. At this point you can start to think about describing some of your services using the UL and the language of domains and contexts. By that point, people should start to click that this makes life easier - there is less confusion, and you're now all working together to get a shared understand of the design and the point of DDD is that the design and the code match. The first part (all 100+ pages of it), of the Millet and Tune book on DDD will pay you dividends here. If that doesn't work, look around for somewhere else to work that understands that software development is often a team sport and is committed to making that happen.
atoav 7y ago
So knowledge about: - the problem you are trying to solve - how you could solve it - how you actually did solve it - which solutions come with which flaes and merits
JamesBarney 7y ago
Haha yeah the number of times I've gotten "Hey someone estimated a task would take 40 hrs on a project you've never seen with libraries you've never touched. mind knocking that out this week?" is astounding.
hising 7y ago
> "Then you have tons of teams, and communication becomes very challenging" communicationChannels = nrOfTeams(nrOfTeams-1)/2 More people should read The Mythical Man-month
cntlzw 7y ago
+ 1 Yes, things really changed for me once I started to ask why we implement things. Tried to understand the manager/customer/stakeholder what is their domain? What kind of issue they want to solve? What is the business case we are working on? I know as a software developer you don't want to do that. More fun refactoring code than dealing with management. More fun writing that piece of SQL than sitting in a meeting. Easier to whine about missing specifications than to understand the big picture. Once I stepped back from coding and looked at the software from a birds eye view, I had actually a much easier time programming features than before. More knowledge, less writing code.
- mr_tristan 7y ago
  Good point: it's far, far better to be proactive, than wait for management to "recognize you". Being a part of the early decision making processes has been a challenge for me as a remote employee. In larger companies, there are lots of meetings, discussions, and decisions that happen before anyone talks to the engineering staff is brought in. But, by basically being nice, asking questions, and really getting involved, I've been able to "weasel" my way into some of these discussions. Once you get involved early on, there's so much more clarity around the one liner "requests" that often get farmed out.
_pmf_ 7y ago
> This struck a chord with me: "Software Is about Developing Knowledge More than Writing Code" Managers are very unhappy when I tell them of all the knowledge I've developed.
deleted 7y ago
[deleted]
kgwxd 7y ago
The first place I worked as a software dev had an owner that would explain everything about the business and the problems to me in very good detail. He would just stop by my desk whenever he thought of something he thought might be good for me to know. Eventually understanding the business became just as interesting as the coding. These days, I hate getting a task without knowing the business side of things or not being able to discuss it directly with the person that does.
drderidder 7y ago
I think this is also known as the fallacy of the fungible engineer / myth of the interchangeable programmer.

civicsquid 7y ago

One of my professors condensed that point into something I thought was clever: "Software engineering is the distilling of ambiguity". I think about that whenever I get frustrated about a vague spec or lack of details. It's the job!

onion2k 7y ago
"Software engineering is the distilling of ambiguity" I hope he meant separating out the ambiguity rather than concentrating it. :)
- hguant 7y ago
  I can see it working both ways - in many cases, I'd like my ambiguity distilled down to one specific point, while the rest of the project deals with lower specific ambiguity (where ambiguity in my mind is equal to "is this thing possible").

mmatants 7y ago

Apparently, Peter Naur (the N in BNF) wrote this up nicely back in 1985 in "Programming as Theory Building": http://pages.cs.wisc.edu/~remzi/Naur.pdf http://pages.cs.wisc.edu/~remzi/Naur.pdf

sword_smith 7y ago
I only have one year of formal CS education but that paper is one of my favorites on the topic. Naur is also the founder of CS at the University of Copenhagen, the place where I studied :)
mcnichol 7y ago
You should consider making this it's own article. "...the designers job is not to pass along "the design" but to pass along "the theories" driving the design. Knowledge of the theory is tacit in owning..." Well said. Thank you!
- fsloth 7y ago
  I would prefer people read the original paper than any second-hand explanation of it. The paper is very readabale and understandable, and is probably relevant as long as into the future as human beings write code.
  - majewsky 7y ago
    When mcnichol said "make this its own article", they probably meant to submit the link to HN as its own submission, not to blog about it.
    - mcnichol 7y ago
      Yeah, that's what was meant. Totally agreed with the statement above this one, it reads well.
fsloth 7y ago
I was about to suggest the same thing. This paper should be mandatory reading for anyone that is professionally involved in a software development project.

clumsysmurf 7y ago

> "Software Is about Developing Knowledge More than Writing Code" The company I work for uses Scrum. They consider the User Stories + the code to be everything you need. I struggle with this, but my manager says they don't want to get tied up doing documentation "because it goes out of date". Beside, they are being Agile which "prefers working code over comprehensive documentation". I am wondering what other companies do to capture this "distilled knowledge". The backend services I rely on are undocumented beside some paltry swagger that leaves much to be desired. The front end has no product-level "spec", if you want to rebuild the thing from scratch. There isn't even a data dictionary, so everyone calls the same thing by different terms (in code, and conversation). There are just user stories (thousands) and code. Does anyone have any suggestions on how to fix this?

gnaritas 7y ago
Knowledge is captured in people, not code. The code is byproduct of the people, the people who are the asset.
tannhaeuser 7y ago
This is not necessarily in opposition to what TFA states: that programming is about knowledge engineering. It just happens that knowledge flows through user stories and code. This might work well or not so well for your team, and there's nothing to fix here. Managers should be aware, though, that this means you no longer have a project, but a line organization put up indefinitely, and where when the teams is disbanded, no "product" as such does remain; nor would it be possible to hand-over the "project" to an offshore team.
PaulRobinson 7y ago
"prefers working code over comprehensive documentation" does not mean "don't do documentation". Documentation is essential. How things work is an important thing to document. Ideally it should be in version control and be generated from the code, because then it's less likely to go out of date. It still has problems (What do you do when the code and the documentation disagree? Which is correct?), but they're not as severe as the problems that arise when there is no documentation at all. What is less useful is having comprehensive documentation for those things that are yet to exist. Writing a few hundred pages of specification and handing it over to the dev team is waterfall, and it is _this_ that the Agile manifesto signatories were interested in making clear. I'd fix it with strategic DDD - I'd develop at least a "ubiquitous language" (or a UL): I'd get others to work with me on having clear terminology and making sure that is used consistently both in user stories and in the code base. That's table stakes. I'd then event storm the contexts I'm working in and start to develop high level documentation. Even at this point relationships between systems emerge, and you get to draw circles around things and name them (domains, contexts), and the UL gets a bit better. At this point you can start to think about describing some of your services using the UL and the language of domains and contexts. By that point, people should start to click that this makes life easier - there is less confusion, and you're now all working together to get a shared understand of the design and the point of DDD is that the design and the code match. The first part (all 100+ pages of it), of the Millet and Tune book on DDD will pay you dividends here. If that doesn't work, look around for somewhere else to work that understands that software development is often a team sport and is committed to making that happen.

atoav 7y ago

So knowledge about: - the problem you are trying to solve - how you could solve it - how you actually did solve it - which solutions come with which flaes and merits

JamesBarney 7y ago

Haha yeah the number of times I've gotten "Hey someone estimated a task would take 40 hrs on a project you've never seen with libraries you've never touched. mind knocking that out this week?" is astounding.

hising 7y ago

> "Then you have tons of teams, and communication becomes very challenging" communicationChannels = nrOfTeams(nrOfTeams-1)/2 More people should read The Mythical Man-month

cntlzw 7y ago

+ 1 Yes, things really changed for me once I started to ask why we implement things. Tried to understand the manager/customer/stakeholder what is their domain? What kind of issue they want to solve? What is the business case we are working on? I know as a software developer you don't want to do that. More fun refactoring code than dealing with management. More fun writing that piece of SQL than sitting in a meeting. Easier to whine about missing specifications than to understand the big picture. Once I stepped back from coding and looked at the software from a birds eye view, I had actually a much easier time programming features than before. More knowledge, less writing code.

mr_tristan 7y ago
Good point: it's far, far better to be proactive, than wait for management to "recognize you". Being a part of the early decision making processes has been a challenge for me as a remote employee. In larger companies, there are lots of meetings, discussions, and decisions that happen before anyone talks to the engineering staff is brought in. But, by basically being nice, asking questions, and really getting involved, I've been able to "weasel" my way into some of these discussions. Once you get involved early on, there's so much more clarity around the one liner "requests" that often get farmed out.

_pmf_ 7y ago

> This struck a chord with me: "Software Is about Developing Knowledge More than Writing Code" Managers are very unhappy when I tell them of all the knowledge I've developed.

deleted 7y ago

[deleted]

kgwxd 7y ago

The first place I worked as a software dev had an owner that would explain everything about the business and the problems to me in very good detail. He would just stop by my desk whenever he thought of something he thought might be good for me to know. Eventually understanding the business became just as interesting as the coding. These days, I hate getting a task without knowing the business side of things or not being able to discuss it directly with the person that does.

drderidder 7y ago

I think this is also known as the fallacy of the fungible engineer / myth of the interchangeable programmer.