What I learned after managing a small team for 2 years
luispcosta.com
luispcosta.com
What I learned after managing a small team for 2 years is that documentation is only good if the team can find it, if the team bothers to look for it, and if the team takes the time to read it. I can't tell you how many times I've linked pertinent documentation in Confluence from the Jira task, only to have the developer ignore it.
What black magic do you have to cast to get devs to look at the documentation?
README.md files in each repo, and code level documentation. The readme file can point to useful links, such as diagrams or stuffy documents where needed.
Links? Parent poster just mentioned he was putting relevant links in JIRA tickets - to work on a feature dev has to open the ticket anyway but suprise-suprise they were not clicking the links.
How on earth README.md links will help in such situation.
Not use Jira and Confluence?
More seriously, I have found that confluence is where documentation goes to die. Something about the tooling, the slowness, poor search, admin tools leading to overzealous compartmentalization, not-quite-good plain text format, awkward gui editing tools, versioning system, distance from the code[1]... something... just makes it not really great at being a repository for keeping documentation up to date, or easily usable.
[1]: eg. not using the same tools/editors to modify the documentation as you do the code
I'm personally a fan of one massive README with a table of contents for technical docs. YMMV.
Also, definitely link the docs in the description and not the comments. I've found that you should never rely on anyone reading the comments (or re-reading them, at least). Any important info that is surfaced in comments should be moved to the description.
Of course, if you're team isn't going to read tickets then that's just a plain problem.
Only times when it was slow it was long time ago when it was on premise and business always skipped upgrading any servers so admins had to run it on tight rope.
Well no we're not - if you're using "cloud" then you get randomly assigned an instance, some of them are fast and some of them are slow (presumably because of who you're sharing them with). Guess you're one of the lucky ones.
> Only times when it was slow it was long time ago when it was on premise and business always skipped upgrading any servers so admins had to run it on tight rope.
Nope, even on big hardware it was always interminably slow.
That's not how documentation works (in my experience). Ignoring documentation is fine (perhaps I don't need documentation to get things done?). The problem is having the need of documentation and find that none exists; that's the real issue. If there's no documentation, as an engineer I have 2 options: a) read the codebase, b) ask around. Whatever option takes less time and is more accurate wins (and take into account that the code may contains bugs, so the code is not always a reflection of the intended business use cases... on the other hand no-one may know what the codebase is supposed to do).
Documentation is like having a fire extinguisher: hopefully you won't need it most of the time, but if in that single occasion that you need it you find none, well, imagine.
So then the author becomes the index and wonders why they keep getting asked.
Documenting your work seems to be a lost art nowadays in many teams, yet it still is something tangible which we left during our work just next to the source code.
We just recetly posted a short text on how we do it at Stratoflow:
If it is too big to go entirely in the code, summarize it in the code and then link to the full docs (ideally in markdown files inside the repo).
Another thing, which you can't really fix yourself, but which I'm still gonna shout into the ether: Ideally you have a browser-based code browsing tool, like GitHub or Gitlab, but one that actually lets people click through method calls into their definition. In my view, that's really the only sane way to read documentation outside of an IDE.
There is nothing worse than having to chase a tangled graph of google sheets, word documents, readmes, confluences, and figma diagrams in order to understand a piece of code. Just put the whole bloody thing in a little documentation file in the class and be done with it.
Better yet, actually use the python docstrings or java docstrings (whatever you call them) and generate the sphinx doc or java doc.
Look at this wonderful documentation one-stop-shop for the python flask repo that was autogenerated with sphinx. https://flask.palletsprojects.com/en/2.3.x/
We're talking about documentation related to the software's architecture and implementation, right? If so, and we haven't veered into talking about some other kind of documentation, then the primary audience for it is the people who work on the code, or on a project that depends on that code, and the best UX for that audience is to have it right in the code or (second-best) linked from the code. It's deeply weird to expect people working on some_product/application.py to open their browser and search for "some_product application documentation", rather than writing or linking it right there in application.py.
But as you point out, there are other audiences who may be interested as well, and they should have access to and be able to easily find (and be trained on how to find) the documentation in or linked from some_product/application.py, when they have some reason to be interested in that. Personally, I don't think the popular web repo navigation interfaces are very good (because they are very static and you can't click around to definitions much or at all), but they are still good enough to read file-level documentation, and to follow links.
I think it's fairly telling that you started this thread with "What black magic do you have to cast to get devs to look at the documentation?" and have then pretty aggressively rejected all the simple answers to that question. I think I've figured out what the problem is with the developers not reading documentation at your org... You may want to find a mirror to look in to see it! I think the person you see in that mirror may be hindering the existence of documentation in a place and form that is useful to the developers they work with...
I only rejected your answer. I didn't reply to anybody else. How telling is that?
But my criticism of your attitude stands. If this is how you responded to developers on your team making obvious suggestions about how to make documentation useful to them, then it's no wonder you've had this problem of people not reading documentation.
Again, this just isn't a problem most teams have, because there are good solutions.
[0]: After multiple warnings, inevitable complaints from the other team members, efforts to help you improve, etc. I don't fire people willy nilly.
Ha, I sincerely doubt our higher-context interactions in an actual working environment would go the same way as our internet strangers with no context discussion.
But it is definitely possibly that we wouldn't ever be working together. Right from the jump, the way you framed the question of "how do I get devs to do what I want them to" suggested that you're more a top down do-what-I-say leader than a servant leader, and that's fine but it's not the style of organization I look for when evaluating hiring managers.
Then you aggressively dismissed a frankly very boring suggestion that has been a best practice for decades. Which was just a weird reaction IMO.
But again, I suspect you would be more tactful about your response to it in an actual workplace, and I would probably be less likely to tell you how strange I found your rejection of such a simple suggestion.
But my mea culpa was about forgetting which thread I saw your comments in, not about my evaluation of your (to me) pretty mystifying attitude about this.
Documentation is both "javadoc" and "architecture diagrams and business reasons for what to build and why at a high level". And it's also useful to have a level in between, in the repo, that is more higher level than class-and-method-level "javadoc", but more technical than business-level documentation.
What I was trying to say is that if you want developers to read the business level documentation, you need to link to it from the in-repo documentation that the developers are already reading in order to do their jobs.
No IC is going to navigate to the business-level documentation and just start reading. What would be the trigger to do this during the course of their day? No, they're going to follow a link from somewhere. You have to put links in the right places!
Doesn't keep up. I would include product documentation too.
First is that documentation is only worth it if you are keeping everything surrounding it stable. Software has been changing a ton in the past few decades such that a lot of documentation from last year is irrelevant. I /think/ this is slowing down, but I can't say for sure. Examples for this are many. Python 2->3, Web frameworks 10 years ago (this one has legit gotten better), general systems management and deployment.
Second is that it was easy to get burned by documentation that was really more of a promise of things to come. By that I mean you think you are going to buckle down, research the right way, and make progress. Only to find out that all of the time you just dumped into the "right way" doesn't actually work today. It may work next week, but if you want to do something today, you have to do it the way they did it before. Which is a ton of warnings about how you will need to be prepared to upgrade, at this point. Examples of this, for me personally, have been trying to use XHTML back in the day, WSDL promises, and now OpenAPI.
> Good, Well Indexed and Easy to Find documentation is everything.
The whole point of agile software development was to make it possible to adapt to an environment with frequently changing requirements. The hint is in the name — agile. How can "very frequently changing priorities" be a factor against agile software development is completely beyond me. "Agile" doesn't mean "scrum done badly", if that's what he is implying.
Pretty sure having motivated people who find the work kinda fun destroys agile/any other methodology. When people wake up excited to pull down tickets or just get shit done, you're doing business right.
What open-source projects in particular do you have in mind? And what do they run on, exactly? And what would this model look like if transplanted into a business setting?
I can see some aspects of agile project management in open-source projects. One, transparency/visibility. Two, working software over documentation. Three, customer feedback. In fact, some large open-source projects have introduced channels for early interactions with customers (i.e. developers) — for example, the RFCs initiatives of React or Lit, or community engagement in various html or css work groups.
I do not know how well developers on open-source projects coordinate/communicate between each other. Or how work gets prioritised. I've certainly seen a fair number of failures in that aspect of open-source projects.
Everything else seems incidental
Re: that fun thing, yes, but most projects aren't fun on a daily basis.
In any case, what I originally meant was that agile is not perfect, but if you've seen startups who don't know any development workflow (ie neither agile nor cascade), software dev grinds to a halt really quickly as they try to reinvent an entire field of management.
Treat it like a normal job. Often no "management" is needed. Get done what you can, talk to you tomorrow.
Agile (capital A) processes have always been trying to sell the idea that a mediocre team can be elevated if they have the right process to guide them. Whether that actually works when the team isn't good enough to self-organise anyway is debatable but that's the sales pitch.
The word "good" here is very vague :-) People can be well-intentioned ("good"), but disorganized, unskilled, or wishful-thinking. People can be strong programmers ("good"), but work by themselves, without coordinating with others. People can be good, yet have managers micromanaging them. People can be good, yet required to work on different projects at once, which breaks focus. People can be good, yet separated from the customers of stakeholders by a layer of managers. People can be good, but required to analyze and estimate the project before even starting working on it, and then be held accountable for their estimate when they run over time. And so on, and so forth.
The cottage industry came out of that pretty quickly and development process often turned into some manager or PM using the first Google result about SDLC.
I somewhat agree overall, but the origin story and the context that the original agile manifesto people were consultants I think is an important context
> The previous system the team was following was something very close to a Kanban system.
The team was already operating in an agile way.
Sprints don't have to be 2 weeks or more - if stuff changes weekly you do weekly sprints.
I just fail to see how one can build anything if priorities change on a daily basis. Most of the features I work on take 2 days at least with 3-5 days most. I can see how one might need to change priorities once a week because you see bunch of stuff built get someone to check it, plan new things that need to be done or adjusted.
I am quite experienced but to get meaningful feature worked out it is at least a day of work.
I can imagine if someone comes up with text changes, color changes or wants to move buttons around on the interface I could probably spit dozens of these in a day.
I experienced something like this in a startup where I was one of five engineers. We were lucky to have individual offices at the end of a hallway. The CEO would walk down the hall a couple of times a week, stopping in each office, and change priorities on us. He had no idea how disruptive it was and always laughed when we told him.
Eventually the CEO saw that we were making very little progress, but attributed it to lack of engineering management rather than priority churn. He was absolutely right, because part of management is managing up. Luckily he hired someone who was great at that.
The new manager spent time talking to each of us about our frustrations and then watched everything for a few weeks. He then realized that the priorities were going in circles - every few weeks the CEO would get back to the priorities from a few weeks earlier. So, whenever the CEO changed the priorities, the manager would say "we're on it" and not tell any of us. It took us a while to figure it out, but he'd also stall our releases until the "new" priorities lined up with what we were ready to release. Both productivity and morale sky-rocketed. And the CEO was happier than ever. I worked with the same manager in two other companies in subsequent years - I never felt as productive under anyone else.
As I gain experience I see how important managing processes, requests and expectations is.
The software and systems we build are a part of organizations and people with their personal agendas expectations and patterns.
Seeing how everything is connected (all at once ;) is an incredible superpower, a true “Whoa” Neo moment.
I am starting to apply my engineering skills to people and organizations, in the best meaning of the word - by seeing what they need, honoring what they are, approaching them with best intentions and clarity.
I'm flummoxed as to how someone can not see this. Can you not run a little thought experiment on yourself, like...
"How much could I get done if every 3 days, I told someone to stop in the middle of their 4 day task and do something different?"
It's not 'management rocket science', it seems it's just basic human behaviour. If every couple of days, someone kept giving the CEO new/different tasks, would he ever expect to be able to get anything done? How can you not see the root cause of such a plain-as-day problem? Willful ignorance?
I tried to convince a CEO of this once and he initially just got angry, then started to parse it as my personal need that he might need to make allowances for due to neurodiversity or something. That all his engineers might work better if they could focus on a task for more than a day was too far outside his world view to be believable to him. And this wasn't a stupid guy, no matter what it might sound like.
He might not lack intelligence, but a CEO unwilling or unable to understand the other people work in a different way to him /is/ stupid.
CEO is management, and (effective) management means well... managing the various people, resources, and other restrictions to achieve the goals at hand. Being pissy that people and the universe don't work they way they want is immature and/or incompetent.
I disagree, a CEO is not management in the sense you are describing. Being a CEO is more about decision making and direction setting for the organization holistically to maximize the value to the shareholders of the org. Depending on the size of the org, management might be a task they perform, but in larger orgs, CEOs rely on managers to manage.
For example, if a CEO in a large org demanded that engineers are all available via phone for level 1 support calls to cut support costs - that would be stupid, because even two short calls a day is going to have a massive impact on those engineers productivity on building the product(s), followed by any of the half decent engineers leaving for other jobs shortly afterwards.
However, if the strategic need of the organization required that level of direct engineering support more than the specific engineering productivity…it could be a sound decision.
As an example, I worked at a organization in the late 90s managing field engineers. For an entire week the CEO required our team to be in office instead of in the field. We thought it idiotic at the time, but apparently it help create the optics that convinced the owner of a small company to sell his company which allowed our company acquire a game changing product.
None of us understood the big picture because we couldn’t see the forest through the trees.
It's glorified to-do lists with an opinionated cadence on how often features get deployed. Do we really need an entire discipline to communicate those simple things.
How flexible are we with requirements ? How many stages are in the to-do list ? How many hierarchies are in the todo list? How often do we features to be deployed ? What more do you need to know ?
Takes 1 long meeting establish a well-communicated bespoke development cycle for each team. Do we really need a phrase for that ? My experience tells me that the system gets sub-optimally molded to suit the implicit development style of the team whether you like it or not.
I hate all the meetings, which we can "feel" don't make sense. When we all "feel" a meeting makes sense, we naturally hop in. Totally different vibes.
Apparently we do, since we still get people who want estimates months in advance (and then want to punish you if those estimates were wrong), who want to commit to a plan and then follow it and then change it without changing the deadlines, ....
> My experience tells me that the system gets sub-optimally molded to suit the implicit development style of the team whether you like it or not.
Isn't that precisely the proof that the development processes haven't been communicated clearly enough and got enough buy-in/consensus?
Its almost like the real world has deadlines and interactions with 3rd parties who need to schedule things too.
What do I mean by those two claims?
The first, software development is inheritently unpredictable. To explain with an analogy, software development is more like writing a mystery novel than it is like building a house. In construction, the steps for each part are mechanical and the time to do so is well trodden and predictable. When a construction project starts, you can schedule the concrete trucks for specific days and generally be 99% right. Software development on the other hand is more liking writing a murder novel.
Rather than commiting to writing a novel which you then might not like, instead we say, "okay, we're going to show you each chapter after we write it and you'll reserve the right to change up the entire story entirely as you see each chapter that is written." That allows the customer things like: "ooh, I really like this secondary character, could we start writing them into the story more!"
From a requirements perspective, it's akin to film-making (film making is even more predictable than software development!!) - it's like getting the requirements: "write me a star wars prequel movie!", I then go off and do it and you get Jar-Jar binks - it's a shame to find that out all the way after the film has been made.
So, the main conflict I see is we are trying to use a process to say things like: "this book will be done in about 3 months [6 iterations, because we have estimated the product backlog and divided by a well known velocity, and we have even left time for unknown ops problems, bugs and even tech debt pay-down!]. At about the 2 month mark we can bring in the compliance and legal teams (or something like that)." Yet, all the Scrum process really allows is to give the client the right to change direction, it's not there to protect that 3 month time frame. Thus, the claim it's not meant to protect the clients schedule, Scrum is not there to protect that 3 month time frame (if anything it's there to help ensure that time frame can be adjusted [probably upwards] as the product develops)
In a way, it's like blaming the maps app for scheduling problems. The maps app can help, but inherently it's not there to make sure a meeting can start on time.
Its actually the exact opposite - when making films they don't shoot the scenes in the sequence they are viewed, they will shoot every scene at the same location in one go due to the cost of setting up equipment, getting staff onsite etc.
The exact opposite of agile.
Scrum really jettisons a "final" date idea, which is something you have in movie-making. Scrum tries to optimize for reactiveness so that a correct product can be made, those potential changes in direction allowed by Scrum all add time to the final product being completed.
It's an interesting analogy I think overall because software development is viewed akin to construction of a building. On the spectrum of predictable schedules, movie making and construction are on the predictable sides of the spectrum, software development is way on the other side of that spectrum.
In short, when someone says "hey, in the real world we have things like 3 month deadlines. Using Scrum, we'll help ensure we hit that!". I just want to point out that Scrum is not a tool to help hit a 3 month deadline at all. It's just there to ensure that you don't commit to a 3 month deadline, build something that turns out to be the wrong thing and needs to be thrown away at that 3 month mark. It's actually a process to extend deadlines! Every 2 weeks you can get a change in direction that causes a one week (or more) of extra scope increase and/or churn or redoing previous work.
Sounds like you needed to be very agile! But maybe not Agile(tm).
Honestly Kanban (what they were doing before) is a great fit for this sort of environment. But for a small team maybe you don’t even need that much structure.
I’ve worked for a few orgs as a TPM. If you can get by with a kanban board and weekly sync meetings, and everything else async, do that.
If you need more rigor or the team is big enough or developing software that would benefit from Scrum, then go for that.
Most importantly, get team input and buy-in. There’s no point in dictating process to teams if they’re not into it.
I know the theory about reducing scope, but my experience has been 100% keep the scope and reduce the quality.
This ^^ is the sign of a future good manager.
but ya it's really more scrum and associated bs that i have a problem with vs og agile.
That's something the retro itself should do. First part of the retro should be reviewing the results of the last retro and what's been done about them. (And WTF are you even doing in the retro if you're not coming up with actionable things?)
> scrum master or agile guru
Lol no, I think those are probably scams. Actually doing agile works, but those positions are probably anticorrelated with actually doing agile.
"If I had to do it all again, I would have immediately sat down with each team member individually to hear their thoughts about:"
Do that and then do it again collectively and do it repeatedly. People need to be needed. People need to be valued. People who feel needed and valued tend to perform best. You don't have to be best mates or even like each other - that's tricky but do able.
Agile is very often not the answer, because on a small team you don't have all of the people and roles necessary to do agile "right". I tend to just do Kanban with frequent demos and milestones.
I agree on documentation. I try lead by example and document all the important bits to a "hit by a bus" level. Because on a small team losing one person means losing a big chunk of knowledge.
It would not shock me in the least if people work in an org where they say they are "going agile", takes them through training where some Scrum Salesman conflates agile with scrum, leading to observations like "agile doesn't deal with change fast enough"
Honestly, we need a new word for it at this point.
Sometimes one big change is better than constant small changes
can be generalised to: Agile is never the answer.
But on a serious note, like it or not Agile is sometimes the answer.
Or a project plan that gets iteratively more detailed as you get closer to the work.