Working Code Podcast - Episode 035: Being A Swamp Guide
Software is never "done". And, as it continues to evolve over time, it often gathers a lot of accidental and essential complexity. This makes it harder to on-board new engineers into a legacy application (and a legacy organization). Enter swamp guides: the aged and battle-hardened staff who know where all the bodies are buried. These guides can hand-hold new team-members as they walk fresh-eyes through the fog of war, helping them to understand where everything lives and how everything works. And, hopefully, leave the swamp a little cleaner than they found it.
... featuring these beautiful, beautiful people:
- Adam Tuttle → Website, Twitter, LinkedIn
- Carol Weiler → Twitter, LinkedIn
- Tim Cunningham → Twitter, LinkedIn
- Ben Nadel (that's me) → Website, Twitter, LinkedIn
With audio editing and engineering by ZCross Media.
For the full show notes and links, visit the episode page. And, be sure to follow the show! Our website is workingcode.dev and we're @WorkingCodePod on Twitter and Instagram. Or, leave us a message at (512) 253-2633 (that's 512-253-CODE). New episodes drop weekly on Wednesday.
Reader Comments
We've replaced "hit by bus" with "wins the lottery" as it feels less gruesome.
The current team I'm on doesn't have anyone that's been on the team less than 9 years, so we're all swamp guides at this point 😎
FWIW: I feel the same way about Confluence as you do Ben, in that I never feel like I can find what I'm looking for. We've moved over to Microsoft Teams, but now instead of Confluence, it's now Teams where I can't find anything.
@Danilo,
That's amazing that your whole team has been there for so long. I'd be curious to know how you feel that affects the team dynamic. And, if there are other teams at the company that are less experienced. On my personal team at work, I think the most "recent" engineer has been there for 7-years 😜 and, I really think it helps our team operate quite smoothly. And, I think it gives my team a lot of confidence to act even without explicit direction.
I know this sounds crazy, but I've tried to pitch the idea of having all documentation on a single page. That way, I can just do
CMD+Fto look for things; and, it will be easier for people to see if they are about to create duplicate content (since finding it will easier). Plus, by creating one mammoth page, it would force us to be much more judicious about what we add. No documenting stuff just for the sake of documentation; when it's all jammed there in the same place, you have to ask the tough questions about whether or not it would be worth documenting.Of course, no one else agrees with this approach 🤣
The one page approach to documentation is great if you have a limited scope. The taffy docs are one page (per version). Even that is pretty long, and Taffy's scope is very tight.
If (anyone) isn't already aware of it, the 4 types of documentation (https://documentation.divio.com/) is definitely worthy of some attention.
@Ben,
We're currently only a team of 3 (was 4 about 2 months ago, and that person was there just over 9 years), and the only dev team in the company. By necessity, we've all taken over certain areas (fiefdoms?) of our applications, which of course, has both been good and bad. The good is that the person that knows the app/feature the best really knows it, but when they aren't available, it slows any progress down quite a bit.
I can see the appeal of having documentation in one place, especially given the searchability of it, but as Adam has mentioned, the scope of the document (and in my opinion the audience too) needs to be carefully thought out. Thanks for the link Adam, I have queued up the "What nobody tells you about documentation" presentation to watch later.
My thoughts prior to checking out Adam's link:
One example might be documentation for a new feature/product, it will probably be written one way if the target audience is a dev team member. If it's for a user of the system it might be written another way. And if the audience if the purchaser of the system (as distinct from the users) it could be written entirely differently. And keeping all three version in the same document then runs into how do you separate out the targeted content for the appropriate audience. That can all be managed, given the appropriate efforts assuming a net positive benefit for your team/company.
It's a hard problem making content accessible as well as focused, maybe that's the next big thing from Invision 😎
@Adam,
I haven't heard of that -- I'll have to check it out. Agreed with limited scope; but, to that end, it can also force you to have a limited scope. Like allowing yourself only to use one suitcase on a trip. It's a forcing function :D
@Danilo,
Ah, I wasn't even really thinking about different audiences of a system - I tend to have tunnel-vision for other engineers; and, I mostly work with internal documentation. But, I agree - keeping separate "information experiences" for different audiences is probably a good thing.