5 ms·

Developers should be forced to write more documentation. Because if you create easy to use software, not a lot of documentation is needed. If you create diffic

by andix 4y ago

Developers should be forced to write more documentation. Because if you create easy to use software, not a lot of documentation is needed. If you create difficult solutions, you need to create a lot of documentation. And there is nothing that people hate more, than writing documentation :).

pixl97 4y ago
We're acting like the programmers want to create the complicated software, but really its the sales team showing up to project management saying "We signed a million dollar deal because our product does X"... then the PM panicking telling the programers that the application needs to do X by next week.
- andix 4y ago
  I’ve seen a lot of programmers/architects who created way to complicated solutions. Distributed microservice applications, nosql, and so on. New technologies that seem cool and useful, but make stuff much more complicated then it needs to be. Without real benefits. „But we can scale from 500k to 50 million users now“, which usually doesn’t happen. But what does happen is, that the system gets too complicated and too hard to extend or fix bugs.
  - sopooneo 4y ago
    I struggle mightily with this in managing projects. My instinct is to use solid boring tech, and maximize chance of delivering on time. But I've found that: 1.) No one writes blog posts about using old boring stuff and meeting expectations. And such blog posts can contribute to recruiting and even, indirectly, sales, by helping your company get general press for being "on the cutting edge." 2.) You can potentially get better overall results even if the new tech has more gotchas and unknowns, because certain developers will knock themselves out to deliver on time and prove you were right in trusting them with the platform/language decisions. But you have to pick very wisely on this and keep in mind such devs may immediately lever their experience on the new tech to get a new job and leave you with a team of juniors that wander lost without their guru.
    - andix 4y ago
      I think it’s still possible to use some modern aspects in combination with boring old tech. One thing I found useful is: try to build something that is boring old tech, but the boring tech can be switched out easily. Like a monolith that can be also split up into micro services (via a build flag).
    - whstl 4y ago
      I don't think "solid boring", or even old, is necessarily bad for recruiting. Typescript and Golang for example, are relatively new-ish but still solid and boring, and have significantly much less gotchas than older established tech like, say, Rails. I don't do Java, but I see it getting a bit of a renaissance. Either because of new features or because people are moving to Kotlin (yep for backends), which is a different language but still has the "solid boring" feel to it. It is tough to hire for devops, though. The currently experienced people want to work with more complex infrastructure. Maybe we need a few more years to see those people getting burned and deciding they don't want to life an exciting work-life anymore.
  - SoftTalker 4y ago
    And there's a vast difference between building a system wuth allegedly scalable components, and actually scaling the system to run. It's way more than just using nosql. I'm also one who uses boring old technology. Mostly relational databases and LTS operating systems. May not make for interesting blog posts but I'll take that over being called at 3:00AM because some microservice isn't working.
    - andix 4y ago
      Exactly. Usually the bottlenecks will appear at places you didn’t expect them in the first place. So I tend to build a system that can handle the load that is expected, and some reasonable scaling (maybe 5x to 50x more load). If your product grows way faster then expected (1000x), you will probably have way more budget, and be able to do it even better.
- whstl 4y ago
  As much as I can sympathize with the fact that sales and PMs tend to invent weird stuff and have weird (and often impossible) deadlines, most of the time it is developers that overcomplicate software. Also, unlike sales/PMs ideas (well, at least a few of them), those complications created by developers aren't really helping sell the software. Nobody is buying software simply because it has 50 microservices, all the design patterns and needs Kubernetes plus a few thousand-bucks per month of cloud to run.
  - javier2 4y ago
    I do disagree with this. It is ok I guess to make these convoluted, half-assed products if the cash flow is fine, but remember you will forever future pay a cost here for increased maintenance and for complicating the next feature.
- bmitc 4y ago
  Sales has a job to do, you know?
- rudasn 4y ago
  The bigger issue in the sales/developers divide is that neither of them is tasked (assessed, paid for, whatever you want to call it) to 1) understand the actual problem/feature request (before even thinking about solutions), and 2) write end user documenration and/or try to explain to explain the solution to the end user. If only sales and dev drive product direction, with neither of them having explicit focus on what the end user needs, you end up with overly complicated, half-assed products, that kind of work, but not really, and nobody wants to touch. On the other hand, what matters is money in the bank, so doing stupid shit like this is fine if the cash flow looks good.
- hsn915 4y ago
  I've never seen a PM come to a dev meeting saying "Hey guys, our sales team decided to use the Kubernetes and an elastic search cluster because our clients told us unanimously that the thought of our product running on an advanced container orchestration monstrosity makes them feel really warm and fuzzy." It's usually the developers telling the sales guy "Sorry man we can't deliver this feature on time because our Elastic Search cluster is on Fire All The Time and we need to fix it before we can start adding new features". https://www.youtube.com/watch?v=y8OnoxKotPQ https://www.youtube.com/watch?v=y8OnoxKotPQ
  - whstl 4y ago
    Love this, and agree 100%. The crazy thing is that I've seen such a situation of the video happen, but it was with a monolith. "No, a junior can't add a filter to this column because the current system doesn't support filtering aggregates, so we have to partially rewrite it. No, we can't add this directly to the controller or model because there's no controllers or models anymore! Or more like: there's just one! Why? Because we wanted a future-proof system and decided to make a GraphQL simulacrum that allows adding new features without almost no cost! Sure, almost nobody understood it and sometimes it requires rewriting, but who wants to working on a fucking CRUD system?"
    - andix 4y ago
      I’ve once worked on a system where everything was abstracted. Literally everything. You were basically not allowed to use any libraries. They had an ORM, but you could only use it via their wrapper („so it can be switched at a later point“). A lot of things were impossible with this wrapper, or just broken. You could file a ticket, but the library was just updated twice a year. You could not make sophisticated HTTP-requests, because you had to use the in-house library. And off course it had much less functionality than some commonly used libraries. So what I learned from that: abstractions can be nice, but they are useless if you can’t escape them. They must have „escape routes“ everywhere, to do things that are not covered by the abstractions.
      - whstl 4y ago
cratermoon 4y ago
As much as I appreciate the value of good documentation, forcing most developers to write documentation would be less than worthless. In part because most people are no good at writing to communicate complex ideas to others. Developers are no better, and may in fact be worse. While they might understand the complex ideas, in trying to explain them to others they run into the Curse of Knowledge. With no skill in turning ideas into communication, the output is at best a first draft of something that might be input into useful documentation.
- andix 4y ago
  Im not talking about end user documentation. More about how to configure and operate the software. How to add features, how to debug issues. How to deploy updates and so on. This is really often missing, I’ve seen it often that a developer quits, and then it takes weeks or months until the next bugfix can be deployed into production.
  - cratermoon 4y ago
    > More about how to configure and operate the software. How to add features, how to debug issues. How to deploy updates and so on. That still implies writing to an audience other than yourself, and the Curse of Knowledge still applies. In many ways, it's much worse, because it's easy to assume that because the document is for a technical audience that the reader will know as much and have the same context as the author, and easy to include less supporting material. I look at StackOverflow and see how many questions are technically answered in the documentation, but in fact do not prevent the question from coming up. It's not the the questioner can't understand or the question is stupid, it's that the mental model of the reader and writer don't match up. Of course it's much worse if, as in your example, the knowledge is in one person's head. That's a related problem, and having something is better than nothing. Even with some documents, cases still arise where there's a missing piece of information that the document author didn't record. The author understood what the document meant, not realizing it is only understandable given some knowledge the author did not provide.
    - 4y ago
ackfoobar 4y ago
> And there is nothing that people hate more, than writing documentation Yes, there is - keeping huge documentation up-to-date.

by andix 4y ago

pixl97 4y ago

We're acting like the programmers want to create the complicated software, but really its the sales team showing up to project management saying "We signed a million dollar deal because our product does X"... then the PM panicking telling the programers that the application needs to do X by next week.

andix 4y ago
I’ve seen a lot of programmers/architects who created way to complicated solutions. Distributed microservice applications, nosql, and so on. New technologies that seem cool and useful, but make stuff much more complicated then it needs to be. Without real benefits. „But we can scale from 500k to 50 million users now“, which usually doesn’t happen. But what does happen is, that the system gets too complicated and too hard to extend or fix bugs.
- sopooneo 4y ago
  I struggle mightily with this in managing projects. My instinct is to use solid boring tech, and maximize chance of delivering on time. But I've found that: 1.) No one writes blog posts about using old boring stuff and meeting expectations. And such blog posts can contribute to recruiting and even, indirectly, sales, by helping your company get general press for being "on the cutting edge." 2.) You can potentially get better overall results even if the new tech has more gotchas and unknowns, because certain developers will knock themselves out to deliver on time and prove you were right in trusting them with the platform/language decisions. But you have to pick very wisely on this and keep in mind such devs may immediately lever their experience on the new tech to get a new job and leave you with a team of juniors that wander lost without their guru.
  - andix 4y ago
    I think it’s still possible to use some modern aspects in combination with boring old tech. One thing I found useful is: try to build something that is boring old tech, but the boring tech can be switched out easily. Like a monolith that can be also split up into micro services (via a build flag).
  - whstl 4y ago
    I don't think "solid boring", or even old, is necessarily bad for recruiting. Typescript and Golang for example, are relatively new-ish but still solid and boring, and have significantly much less gotchas than older established tech like, say, Rails. I don't do Java, but I see it getting a bit of a renaissance. Either because of new features or because people are moving to Kotlin (yep for backends), which is a different language but still has the "solid boring" feel to it. It is tough to hire for devops, though. The currently experienced people want to work with more complex infrastructure. Maybe we need a few more years to see those people getting burned and deciding they don't want to life an exciting work-life anymore.
- SoftTalker 4y ago
  And there's a vast difference between building a system wuth allegedly scalable components, and actually scaling the system to run. It's way more than just using nosql. I'm also one who uses boring old technology. Mostly relational databases and LTS operating systems. May not make for interesting blog posts but I'll take that over being called at 3:00AM because some microservice isn't working.
  - andix 4y ago
    Exactly. Usually the bottlenecks will appear at places you didn’t expect them in the first place. So I tend to build a system that can handle the load that is expected, and some reasonable scaling (maybe 5x to 50x more load). If your product grows way faster then expected (1000x), you will probably have way more budget, and be able to do it even better.
whstl 4y ago
As much as I can sympathize with the fact that sales and PMs tend to invent weird stuff and have weird (and often impossible) deadlines, most of the time it is developers that overcomplicate software. Also, unlike sales/PMs ideas (well, at least a few of them), those complications created by developers aren't really helping sell the software. Nobody is buying software simply because it has 50 microservices, all the design patterns and needs Kubernetes plus a few thousand-bucks per month of cloud to run.
- javier2 4y ago
  I do disagree with this. It is ok I guess to make these convoluted, half-assed products if the cash flow is fine, but remember you will forever future pay a cost here for increased maintenance and for complicating the next feature.
bmitc 4y ago
Sales has a job to do, you know?
rudasn 4y ago
The bigger issue in the sales/developers divide is that neither of them is tasked (assessed, paid for, whatever you want to call it) to 1) understand the actual problem/feature request (before even thinking about solutions), and 2) write end user documenration and/or try to explain to explain the solution to the end user. If only sales and dev drive product direction, with neither of them having explicit focus on what the end user needs, you end up with overly complicated, half-assed products, that kind of work, but not really, and nobody wants to touch. On the other hand, what matters is money in the bank, so doing stupid shit like this is fine if the cash flow looks good.
hsn915 4y ago
I've never seen a PM come to a dev meeting saying "Hey guys, our sales team decided to use the Kubernetes and an elastic search cluster because our clients told us unanimously that the thought of our product running on an advanced container orchestration monstrosity makes them feel really warm and fuzzy." It's usually the developers telling the sales guy "Sorry man we can't deliver this feature on time because our Elastic Search cluster is on Fire All The Time and we need to fix it before we can start adding new features". https://www.youtube.com/watch?v=y8OnoxKotPQ https://www.youtube.com/watch?v=y8OnoxKotPQ
- whstl 4y ago
  Love this, and agree 100%. The crazy thing is that I've seen such a situation of the video happen, but it was with a monolith. "No, a junior can't add a filter to this column because the current system doesn't support filtering aggregates, so we have to partially rewrite it. No, we can't add this directly to the controller or model because there's no controllers or models anymore! Or more like: there's just one! Why? Because we wanted a future-proof system and decided to make a GraphQL simulacrum that allows adding new features without almost no cost! Sure, almost nobody understood it and sometimes it requires rewriting, but who wants to working on a fucking CRUD system?"
  - andix 4y ago
    I’ve once worked on a system where everything was abstracted. Literally everything. You were basically not allowed to use any libraries. They had an ORM, but you could only use it via their wrapper („so it can be switched at a later point“). A lot of things were impossible with this wrapper, or just broken. You could file a ticket, but the library was just updated twice a year. You could not make sophisticated HTTP-requests, because you had to use the in-house library. And off course it had much less functionality than some commonly used libraries. So what I learned from that: abstractions can be nice, but they are useless if you can’t escape them. They must have „escape routes“ everywhere, to do things that are not covered by the abstractions.
    - whstl 4y ago

cratermoon 4y ago

As much as I appreciate the value of good documentation, forcing most developers to write documentation would be less than worthless. In part because most people are no good at writing to communicate complex ideas to others. Developers are no better, and may in fact be worse. While they might understand the complex ideas, in trying to explain them to others they run into the Curse of Knowledge. With no skill in turning ideas into communication, the output is at best a first draft of something that might be input into useful documentation.

andix 4y ago
Im not talking about end user documentation. More about how to configure and operate the software. How to add features, how to debug issues. How to deploy updates and so on. This is really often missing, I’ve seen it often that a developer quits, and then it takes weeks or months until the next bugfix can be deployed into production.
- cratermoon 4y ago
  > More about how to configure and operate the software. How to add features, how to debug issues. How to deploy updates and so on. That still implies writing to an audience other than yourself, and the Curse of Knowledge still applies. In many ways, it's much worse, because it's easy to assume that because the document is for a technical audience that the reader will know as much and have the same context as the author, and easy to include less supporting material. I look at StackOverflow and see how many questions are technically answered in the documentation, but in fact do not prevent the question from coming up. It's not the the questioner can't understand or the question is stupid, it's that the mental model of the reader and writer don't match up. Of course it's much worse if, as in your example, the knowledge is in one person's head. That's a related problem, and having something is better than nothing. Even with some documents, cases still arise where there's a missing piece of information that the document author didn't record. The author understood what the document meant, not realizing it is only understandable given some knowledge the author did not provide.
  - 4y ago

ackfoobar 4y ago

> And there is nothing that people hate more, than writing documentation Yes, there is - keeping huge documentation up-to-date.