5 ms·

That strategy does limit your documentation to text though. Sometimes a literal big picture and a few well-considered supporting diagrams can be worth more than

That strategy does limit your documentation to text though. Sometimes a literal big picture and a few well-considered supporting diagrams can be worth more than a hundred screens of Markdown.

lylejantzi3rd 3y ago
It's also only visible to developers.
- sanderjd 3y ago
  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.
- chinchilla2020 3y ago
  It isn't. It's a basic wiki-style web UI. That's the whole point of things like sphinx and javadoc. All the documentation in your code is easily accessible.
  - lylejantzi3rd 3y ago
    And, as I've said in other places in this thread, it's not reasonable to force non-technical people to deal with your repo. Maybe that's where this whole conversation went off the rails. When I say documentation, I don't mean javadoc. I mean architecture diagrams and business reasons for what to build and why at a high level.
    - sanderjd 3y ago
      Agreed with this evaluation of where we lost the plot in this thread. 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!
      - deleted 3y ago
        [deleted]
sanderjd 3y ago
You can put images and diagrams in markdown documents.
spacemanspiff01 3y ago
[dead]

That strategy does limit your documentation to text though. Sometimes a literal big picture and a few well-considered supporting diagrams can be worth more than a hundred screens of Markdown.

lylejantzi3rd 3y ago

It's also only visible to developers.

sanderjd 3y ago
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.
chinchilla2020 3y ago
It isn't. It's a basic wiki-style web UI. That's the whole point of things like sphinx and javadoc. All the documentation in your code is easily accessible.
- lylejantzi3rd 3y ago
  And, as I've said in other places in this thread, it's not reasonable to force non-technical people to deal with your repo. Maybe that's where this whole conversation went off the rails. When I say documentation, I don't mean javadoc. I mean architecture diagrams and business reasons for what to build and why at a high level.
  - sanderjd 3y ago
    Agreed with this evaluation of where we lost the plot in this thread. 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!
    - deleted 3y ago
      [deleted]

sanderjd 3y ago

You can put images and diagrams in markdown documents.

spacemanspiff01 3y ago

[dead]