Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

What I learned after managing a small team for 2 years

luispcosta.com

Post reply on HN
Print view View original

71–80 of 102 posts

Re: What I learned after managing a small team for 2 years

#71

Post by sanderjd »

lylejantzi3rd wrote: post #69
sanderjd wrote: post #67

Earlier quoted context omitted.

Everyone should have access to the repo's web interface.

That's ridiculous. You can't expect non-technical managers and graphic designers to try to dig around your code base to find what they're looking for, let alone make changes.

I don't expect them to make changes, but I do expect them to have no problem clicking into the web UI and reading documentation in code or markdown files in the repo.

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...

Re: What I learned after managing a small team for 2 years

#72

Post by lylejantzi3rd »

sanderjd wrote: post #71
lylejantzi3rd wrote: post #69

Earlier quoted context omitted.

That's ridiculous. You can't expect non-technical managers and graphic designers to try to dig around your code base to find what they're looking for, let alone make changes.

I don't expect them to make changes, but I do expect them to have no problem clicking into the web UI and reading documentation in code or markdown files in the repo. 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…

> 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 only rejected your answer. I didn't reply to anybody else. How telling is that?

Re: What I learned after managing a small team for 2 years

#73

Post by __pache__ »

azangru wrote: post #65
__pache__ wrote: post #48

Earlier quoted context omitted.

Huh? Why don't lots of successful open source softwares run on agile, then? 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.

> Huh? Why don't lots of successful open source softwares run on agile, then? 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 feedba…

Any open source project? Typically people work on what they care about or what is obviously needed. Go with that flow instead of against it. Hire people eager to contribute.

Everything else seems incidental

Re: What I learned after managing a small team for 2 years

#74

Post by sanderjd »

lylejantzi3rd wrote: post #72
sanderjd wrote: post #71

Earlier quoted context omitted.

I don't expect them to make changes, but I do expect them to have no problem clicking into the web UI and reading documentation in code or markdown files in the repo. 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…

> 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 only rejected your answer. I didn't reply to anybody else. How telling is that?

No, you've taken this same dismissive know-it-all tone elsewhere in the thread as well.

Re: What I learned after managing a small team for 2 years

#75

Post by lylejantzi3rd »

sanderjd wrote: post #74
lylejantzi3rd wrote: post #72

Earlier quoted context omitted.

> 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 only rejected your answer. I didn't reply to anybody else. How telling is that?

No, you've taken this same dismissive know-it-all tone elsewhere in the thread as well.

Where? Quote me. I'm telling you, this is the only part of the thread I've replied to. Maybe you should take a good hard look at yourself before accusing others.

Re: What I learned after managing a small team for 2 years

#76

Post by smcleod »

stock_toaster wrote: post #5
lylejantzi3rd wrote: post #3

> Documentation is everything 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…

> What black magic do you have to cast to get devs to look at the documentation? 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]... somethi…

Yeah confluence and jira both need to go away, both of them make it very hard to find information and feel like such a burden to use.

Re: What I learned after managing a small team for 2 years

#77

Post by BarryMilo »

__pache__ wrote: post #48
BarryMilo wrote: post #37

Earlier quoted context omitted.

Agile is better than nothing, which is what most teams would/did have as an alternative.

Huh? Why don't lots of successful open source softwares run on agile, then? 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.

We could get into a semantic argument about what "lots" means. But open source is very much a corporate thing now, and lots of dev companies do indeed have an agile-inspired workflow at least.

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.

Re: What I learned after managing a small team for 2 years

#78

Post by BarryMilo »

__pache__ wrote: post #73
azangru wrote: post #65

Earlier quoted context omitted.

> Huh? Why don't lots of successful open source softwares run on agile, then? 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 feedba…

Any open source project? Typically people work on what they care about or what is obviously needed. Go with that flow instead of against it. Hire people eager to contribute. Everything else seems incidental

Eagerness doesn't scale.

Re: What I learned after managing a small team for 2 years

#79

Post by __pache__ »

BarryMilo wrote: post #77
__pache__ wrote: post #48

Earlier quoted context omitted.

Huh? Why don't lots of successful open source softwares run on agile, then? 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.

We could get into a semantic argument about what "lots" means. But open source is very much a corporate thing now, and lots of dev companies do indeed have an agile-inspired workflow at least. 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 n…

Disagree, I guess. Agile is worse than nothing.

Treat it like a normal job. Often no "management" is needed. Get done what you can, talk to you tomorrow.

Re: What I learned after managing a small team for 2 years

#80

Post by __pache__ »

BarryMilo wrote: post #78
__pache__ wrote: post #73

Earlier quoted context omitted.

Any open source project? Typically people work on what they care about or what is obviously needed. Go with that flow instead of against it. Hire people eager to contribute. Everything else seems incidental

Eagerness doesn't scale.

Yeah talking about small teams.
Post reply on HN