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 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]... something... just makes it not really great at being a repository for keeping documentation up to date, or easily usable.
[1]: eg. not using the same tools/editors to modify the documentation as you do the code
I'm personally a fan of one massive README with a table of contents for technical docs. YMMV.
Also, definitely link the docs in the description and not the comments. I've found that you should never rely on anyone reading the comments (or re-reading them, at least). Any important info that is surfaced in comments should be moved to the description.
Of course, if you're team isn't going to read tickets then that's just a plain problem.
If it is too big to go entirely in the code, summarize it in the code and then link to the full docs (ideally in markdown files inside the repo).
Another thing, which you can't really fix yourself, but which I'm still gonna shout into the ether: Ideally you have a browser-based code browsing tool, like GitHub or Gitlab, but one that actually lets people click through method calls into their definition. In my view, that's really the only sane way to read documentation outside of an IDE.
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/
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!
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...
I only rejected your answer. I didn't reply to anybody else. How telling is that?
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.
[0]: After multiple warnings, inevitable complaints from the other team members, efforts to help you improve, etc. I don't fire people willy nilly.
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 not how documentation works (in my experience). Ignoring documentation is fine (perhaps I don't need documentation to get things done?). The problem is having the need of documentation and find that none exists; that's the real issue. If there's no documentation, as an engineer I have 2 options: a) read the codebase, b) ask around. Whatever option takes less time and is more accurate wins (and take into account that the code may contains bugs, so the code is not always a reflection of the intended business use cases... on the other hand no-one may know what the codebase is supposed to do).
Documentation is like having a fire extinguisher: hopefully you won't need it most of the time, but if in that single occasion that you need it you find none, well, imagine.
So then the author becomes the index and wonders why they keep getting asked.
First is that documentation is only worth it if you are keeping everything surrounding it stable. Software has been changing a ton in the past few decades such that a lot of documentation from last year is irrelevant. I /think/ this is slowing down, but I can't say for sure. Examples for this are many. Python 2->3, Web frameworks 10 years ago (this one has legit gotten better), general systems management and deployment.
Second is that it was easy to get burned by documentation that was really more of a promise of things to come. By that I mean you think you are going to buckle down, research the right way, and make progress. Only to find out that all of the time you just dumped into the "right way" doesn't actually work today. It may work next week, but if you want to do something today, you have to do it the way they did it before. Which is a ton of warnings about how you will need to be prepared to upgrade, at this point. Examples of this, for me personally, have been trying to use XHTML back in the day, WSDL promises, and now OpenAPI.
Only times when it was slow it was long time ago when it was on premise and business always skipped upgrading any servers so admins had to run it on tight rope.
Well no we're not - if you're using "cloud" then you get randomly assigned an instance, some of them are fast and some of them are slow (presumably because of who you're sharing them with). Guess you're one of the lucky ones.
> Only times when it was slow it was long time ago when it was on premise and business always skipped upgrading any servers so admins had to run it on tight rope.
Nope, even on big hardware it was always interminably slow.
Documenting your work seems to be a lost art nowadays in many teams, yet it still is something tangible which we left during our work just next to the source code.
We just recetly posted a short text on how we do it at Stratoflow:
README.md files in each repo, and code level documentation. The readme file can point to useful links, such as diagrams or stuffy documents where needed.
Links? Parent poster just mentioned he was putting relevant links in JIRA tickets - to work on a feature dev has to open the ticket anyway but suprise-suprise they were not clicking the links.
How on earth README.md links will help in such situation.
Doesn't keep up. I would include product documentation too.
> Good, Well Indexed and Easy to Find documentation is everything.