6 ms·

Love this approach. It keeps everything in a 'one stop shop. There is nothing worse than having to chase a tangled graph of google sheets, word documents, read

by chinchilla2020 3y ago

Love this approach. It keeps everything in a 'one stop shop. 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/ https://flask.palletsprojects.com/en/2.3.x/

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

Silhouette 3y ago

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