3 ms·

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

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.

sanderjd 3y ago
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...
- lylejantzi3rd 3y ago
  > 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?
  - sanderjd 3y ago
    No, you've taken this same dismissive know-it-all tone elsewhere in the thread as well.
    - lylejantzi3rd 3y ago
      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.
      - sanderjd 3y ago
        Oh you're right, I was thinking of another comment in this same thread. Mea culpa! 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.
        lylejantzi3rd 3y ago
        Similarly, if you were on my team, I'd probably fire you[0]. You have no self-awareness. You've doubled down on your flawed misinterpretation of my attitude, even though you've already admitted you came to that conclusion in error. You're the type of person who can't ever be wrong. That sort of thing is murder on morale. [0]: After multiple warnings, inevitable complaints from the other team members, efforts to help you improve, etc. I don't fire people willy nilly.
        sanderjd 3y ago
        Edit to start with this: I think you're right that I was too hasty with my "you need to look in the mirror" comment, and this whole discussion would have gone better without that comment. So I'm sorry about that one! 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.

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.

sanderjd 3y ago

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

lylejantzi3rd 3y ago
> 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?
- sanderjd 3y ago
  No, you've taken this same dismissive know-it-all tone elsewhere in the thread as well.
  - lylejantzi3rd 3y ago
    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.
    - sanderjd 3y ago
      Oh you're right, I was thinking of another comment in this same thread. Mea culpa! 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.
      - lylejantzi3rd 3y ago
        Similarly, if you were on my team, I'd probably fire you[0]. You have no self-awareness. You've doubled down on your flawed misinterpretation of my attitude, even though you've already admitted you came to that conclusion in error. You're the type of person who can't ever be wrong. That sort of thing is murder on morale. [0]: After multiple warnings, inevitable complaints from the other team members, efforts to help you improve, etc. I don't fire people willy nilly.
        sanderjd 3y ago
        Edit to start with this: I think you're right that I was too hasty with my "you need to look in the mirror" comment, and this whole discussion would have gone better without that comment. So I'm sorry about that one! 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.