
Effective Software Documentation with Everett Griffiths - EMx 180
Elixir Mix
Microservices
The number of microservices is like five to 10 times the number of engineers. It's that so much boilerplate, and if there's not a good justification for it, man, you're just like increasing the inefficiency of that. "I've seen microservices abuse more than I've seen them help an organization," he says.
00:00
Transcript
Play full episode
Transcript
Episode notes
Speaker 1
One of
Speaker 3
my favorites is like what microservices are my favorite bad microservices stories is when the number of microservices is like five to 10 times the number of engineers. I mean, yeah.
Speaker 4
Yeah,
Speaker 3
yeah, honestly,
Speaker 4
I've seen
Speaker 1
microservices abuse more than I've seen them hike help an organization. And that's the, that's the same, it just gives me like acid reflux just thinking about that. It's like, what's the, oh man, the law where like an organization's code eventually takes on the shape of that organization's communication. You know, you know, I'm talking about it's one of these terrible quotes, but yeah, I know
Speaker 3
I think it was
Speaker 1
Conway's law or something. Yeah, because like, you have trouble like communicating between like business and engineering or like between the product people and like that other area. It's like, yeah, that shows up in the code where you just have these like crazy walls and like, it's like talking about like wasting time writing boilerplate. It's like microservices. It's that so much boilerplate to like set up your HTTP requests responses or your GPC or like whatever your rope or with RPC good stuff. Like all that stuff is like, oh, that's fine. If like, you really is a good benefit out of it. But like too many times I've seen that it's just not a good use of people's time. And it increases like the load of like having to write the documentation, the tests, the the QA, that all like all that stuff just expands. And if there's not a good justification for it, man, you're just like increasing the inefficiency of that and making it so much harder to deploy and maintain. Like try doing an integration test on a microservice architecture. Like have fun with that. Yeah. It's a nightmare. I found myself like really gravitating back to like the monolithic application because if you structured that well, I think a mixer does this really well, whether you can like scale, because you can pass messages across nodes. It sort of like gives you this thing for free, where you can like develop these things more in isolation. And like that to me, like even getting like SQS out of the picture, it was like a huge win, because we could just like spin up an entire well previously had been like multiple applications having to talk to each other. And then we had to like reset Amazon and like go get coffee and wait while the queue's drained. And then like come back and poke at it. That was a relatively simple connectivity between different parts of the of the applications. Like even that was a pain in the ass. As soon as we pulled that out, like we were able to spin up the whole thing at once easily on like just a laptop running Docker, like not even that efficiency. And like we could test everything, soup the nuts, like everything on it was like, man, that is a huge win. So there wasn't any like dark spots of the app. Or we're like, well, that message went off to some microservice. And we're pretty sure I like did what it was supposed to. But actually we don't know. Like that never was a good answer for me. Totally.
Bad documentation wastes time, costs real money, and makes developers unproductive. Documentation might be bad because it is flat-out wrong (typos, references to an older version, etc.), but more often documentation is bad when it fails to tell us what we need to know. Don’t let all your hard work go to waste because you failed to communicate what your software is or how to use it. Today on the show, Everett Griffiths shares his insights on how to approach documentation simply and effectively.
In this episode…
Sponsors
Links
Picks
Advertising Inquiries: https://redcircle.com/brands
Privacy & Opt-Out: https://redcircle.com/privacy
Become a supporter of this podcast: https://www.spreaker.com/podcast/elixir-mix--6102049/support.
In this episode…
- What got you into documentation?
- Examples, examples, examples
- Having an effective feedback loop
- Key word arguments
- Coding is easy, but documentation is hard
- Using mermaid charts
- Open sourcing your software
- Clean code and clean infrastructure
- Simplifying coding environments
Sponsors
Links
- WTFM: Writing Effective Software Documentation
- Inspecting Ecto Schemas with Elixir | by Everett Griffiths | Medium 1
- Enhancing Elixir Documentation with Mermaid Charts | by Everett Griffiths | Medium 1
- Coding is Easy; Communication is Hard | by Everett Griffiths | Medium 1
- LinkedIn: Everett Griffiths
- Twitter: @fireproofsocks
Picks
- Adi- Grafana OnCall
- Allen- MJML - The Responsive Email Framework
- Everett- Paasaa - Paasaa v0.6.0
- Everett- The Guns of August: The Pulitzer Prize-Winning Classic About the Outbreak of World War I
Advertising Inquiries: https://redcircle.com/brands
Privacy & Opt-Out: https://redcircle.com/privacy
Become a supporter of this podcast: https://www.spreaker.com/podcast/elixir-mix--6102049/support.