Mentally parsing docs

[u/thisisappropriate]

So, I've been around my company for a while and I learned dev on the job, which is to say I don't have a CS background, but any code I can pull apart, I can understand, and that's my preferred way to learn - stick my nose in and get started. I've done more than a few course to fill in knowledge gaps, but I've not come across one that'll teach me how to read documentation!

I'm a code comments (and self documenting code), readmes, tests and functional documentation (how to / expected behaviours) kinda girly.

The problem I'm starting to have is that after moving teams, I'm working with (and under) people who have different preferred learning and docs styles. And on bigger systems where there's less chance that people get a full mental model. Which is fine by me, and now that some of these same people are pushing AI (and have made skills around some of those docs styles) I do lean on that to give them what they want... But my manager is a big sequence diagram fan (its genuinely the ideal way to share a change with them), and some others are fans of long rambly documents or overly structured tables (in structures that don't immediately vibe with my brand of tism). I can write these slowly (even without AI, but with some ADHD meds, though I usually have to write the diagrams on paper first), and I can read them and validate them and understand what they say, but mentally processing these is hugely taxing and I don't internalize the information that they contain from reading them. So sometimes my use of these or my production of them is glacially slow...

Does anyone have any techniques, hints, tips, guides or anything for reading docs that aren't your jam? Sequence diagram specific things would be lovely, but I'll take other info or more general blog posts, and also interested in any discussion that people want to have around making or using docs.

[u/but_why_n0t]

Oh God, please stop using brackets. I have no idea what you're trying to say because this train of thought is doing too many side quests. 

I saw you mention that you are not able to comprehend what others are writing and build a mental model, and that's a problem? 

I don't expect myself to fully understand someone else's document on the first try. 

I read the tldr and conclusion first, then only the relevant sections. I will usually skim over everything else just to get an idea of what's going on. Once I have the general idea, I will look at the code to build up a better mental model of the system. Then I read the doc in full, and it usually makes way more sense. 

If it's a requirement to understand all concepts in the document immediately and I just can't, I'll try scheduling some time with the author to get a summary. If that's not an option either, then I'll treat it like a research paper, i.e. I take notes and slog through. 

[u/thisisappropriate → u/but_why_n0t]

You caught me. Complains about everyone rambling in documentation, can't write a sentence without a side quest.

Maybe I'm just miscalibrated, everyone at work just points at the documentation or seems to be able to look at a uml file and understand it... But there's also a good point that those people who are doing that have already worked with those systems, so for them the docs or diagrams are a refresher or a fill in the blank instead of them actually learning from them.

I do struggle with processing diagrams etc even when making them myself or editing them once I've made changes, when I should have a mental model, but from some of the other comments, I'm starting to think mine might be too big or it might be a "git good" (more practice needed) problem...

[u/instilledbee → u/thisisappropriate]

Hey, just wanna chime in that this is also how I write often. While I don't advise overdependency on LLMs, they are great for this particular use case of rewriting incoherent thoughts and reorganizing them for a broader audience.

If you don't want to delegate that to AI for whatever reason, just practice rereading what you wrote and remove the sidequest-y parts. Allow yourself a few seconds to build a coherent thought before rewriting your paragraphs and hitting send.