5 ms·

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

lylejantzi3rd 3y ago
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.

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.