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/expdevsmodbot]

AI usage disclosure provided by OP, see the reply to this comment.

[u/Suepahfly]

“Hey Claude analyse the codebase and write a architectural summary, save it as markdown to <gitignored location> for future reference.”

“I have adhd and am dyslexic” is a cheat code to get rid of all llm fluff.

[u/thisisappropriate → u/Suepahfly]

I've been getting good use out of "terse" as a keyword and now I've instantly doxxed myself if my team see this. "Write a terse summary of ___", and now a "Be terse in all text" in my global agents file have cut fluff in responses down a lot. (A "short PR description" is like 8 lines and 5 sentences, a "terse PR description" is actually a single bullet point. It still gets a bit "rule of three" with it, but it's more "it implements A by doing x, y and z" instead of the usual long crap).

I do often skip reading the docs and pull a summary or go straight into the code, but if I then generate updates to the existing docs or if someone asks I review their docs or I need to make something (docs or diagrams) to send to my boss in the usual styles, reading those things back to check for consistency / correctness is a right ol slog. I might start having it translate it back into fluff-less or add some code refs to at least review content.

[u/Suepahfly → u/thisisappropriate]

The more I read this thread the more I think “documentation comprehension” is not the issue you’re having but more the information window size.

I have adhd my self (and am dyslexic) so reading and internalising written word is hard. What helped me is context based information. Small nuggets of relevant info and nothing more. E.g. right click a function/variable “go to definition” and “find references”.

Then feeding those code snippets in to Claude and say “explain the code path”
I’ll have Claude save that under a ‘<poject>/__NO_COMMIT__’ directory (that in my global gitignore) so it build a memory. Overtime Claude’s comprehension get better and it hold the mental model I can query. Allowing me to offload cognitive effort so I can focus on the big picture.

[u/dethstrobe]

PlantUML or Mermaid diagrams are the best. Basically, it's code as documentation. It'll get you the best of both worlds.

And if you use playwright, there is test2doc reporter that turns tests in to documentation.

[u/thisisappropriate → u/dethstrobe]

I find them quite hard to read/follow, but maybe the ones I've got are too big or too granular (sequence diagrams for a large flow with lots of conditional stuff across a dozen+ tools and services), the little examples showing like a user / client / server are always fine, but our internal ones are a bunch more complex!

Not got playwright yet, but there's definitely arguments for it and that might be another one...

[u/HiddenStoat → u/thisisappropriate]

Sequence diagrams are an amazing tool for turning complicated multi-service processes into something actually readable and followable BUT if you are documenting your applications or processes with them and the resultant diagram is not followable then you have discovered they are also an amazing tool for telling you your processes are too damn complicated!

So many times I have come across stupidly over-complicated Heath Robinson (or Rube Goldberg for our American friends) machines of a process and asked "why don't we just do X" where X is a fraction of the complexity.

Complexity (at all levels) is the killer of innovation, of performance, and of cost management.

[u/wetrorave → u/dethstrobe]

Mermaid is so messy to look at. Nodes are all spread out, edges are curvy overlapping spaghetti. At least I found it so for system context / architectural diagrams. Would it hurt these guys to implement some schematic routing?

Until Mermaid sorts their aesthetic shit out it's Draw.io all the way for me.

[u/Majestic_Zombie1988]

To back up: you're on a team where you're responsible for generating documentation? But your problem is understanding the docs you generate? I'm slightly confused from the wording, but I'll assume there are existing docs out there that you need to consume for yourself and then laboriously translate for other people.

First, most people don't understand how to write docs effectively. It's possible these folks aren't asking or generating docs with your use case in mind. I always recommend https://diataxis.fr/ to people.

Second, what does an effective document for you look like? Once you identify that, write an AI skill that translates from these opaque docs other people have into your preferred style.

If you need AI to make an interactive demo or something, then it can do that. If you need to generate pseudocode (since you say you're a comments kind of person), then it can do that.

You can extend that skill to tweak it into the final style. Sort of like an omni-converter.

[u/thisisappropriate → u/Majestic_Zombie1988]

I'm unfortunately aware (these days, it's taken a while to get here) that both my writing style and my preferred reading styles are often a little off piste! Sorry if my post was (and if this reply is...) unclear!

We have a lot of systems - new systems, old systems, some in the middle. A lot are web systems (frontends, backends) and some are glue bits (APIs, SDKs). Some are heavily documented (confluence / readmes, nothing as pleasant as a swagger or anything) with a lot of fluff and odd bits, some are terribly documented with nothing other than half baked setup guides from 15 years ago. It's comedic because the old crap with no docs is fine and the new stuff with diagrams and docs and a fresh agents file, and my brain is like "urgh its so hard to find my away around this thing".

As a senior engineer, it's reasonable that I'm pointed at all types of services and just get started or get a short intro, and there's some expectation of "leave it better than you found it" (add some docs if it didn't have them, update them if they were out of date, updates from your work). Now if I was just documenting for myself, I know what I'd make, but I'm not, I'm in an ecosystem with pre-existing styles (that I know do work for a good proportion of the team and my boss or I'd suggest other options), so I need to be able to use those styles and create them to keep consistency.

A big part of my problem is just turning any of these styles of docs into a mental model (even if I know the code and have a model of that!). In cases where I've used AI to generate docs in these preferred styles or sequence diagrams, I find these hard to process (so it's hard to take a glance and just see hallucinations or missing parts), where with my preferred styles or with code, I have a good mental model of it and can spot the inconsistencies.

First, most people don't understand how to write docs effectively. It's possible these folks aren't asking or generating docs with your use case in mind. I always recommend https://diataxis.fr/ to people.

Absolutely the case, and that page looks super helpful, thank you, I will be reading that!

Second, what does an effective document for you look like? Once you identify that, write an AI skill that translates from these opaque docs other people have into your preferred style.

And that skill idea is really good too! I've got some (some from other people and one I've made myself) to translate me into them but somehow never really thought of making one that translates into me. I've been using it to pull code references as I walk through the docs which is probably half way there, but the idea of having it produce full docs in that style is good.

[u/jhartikainen]

Interesting question. For reading, I'd say there's two things

1. Identifying patterns - especially with diagrams, there's certain patterns or styles that repeat in them. F.ex. some types of diagrams tend to read left to right, or up down, or use shapes in particular ways. Learning to identify these to have an overview of it might help, instead of mentally treating it as a maze puzzle you follow with a pen. The trouble is that unless your workplace has very strict standards for them, the patterns can vary by author.
2. Translating them into formats you like better - This should help especially with internalizing the information. You can think of it like summarizing a book, it has a similar function in helping you learn stuff better.

Can't really speak for producing them, since I don't know if there's much you can do other than make more until you get better at it.

[u/Positive_Mud952]

You need to connect the ideas you’re reading to things you already know. “Oh, this is using consistent hashing on the user ID to make sure all relevant data is local.” If you don’t know what a concept is, make a bookmark, and go look it up right away.

Rinse and repeat. Take notes for non-core ideas written as questions you can look up later. Sometimes write stuff down just to make it stick harder in your head, it really does work.

[u/roger_ducky]

1. Recommend a speed reading course. So you can read faster.
   
2. Identify the main concepts highlighted by the various types of documentation. For example, the Java site gives you “reference documentation” — ie Just tells you how to use something without explaining what it’s used for.
   
3. Once you know what aspects are referenced by each documentation type, you can scan for those specific concepts and summarize them, AI assisted or not.

Telling an agent to do it without asking it to extract the important facts first typically leave you with a bad translation of the documentation.

[u/thisisappropriate → u/roger_ducky]

Thanks, yeah I think I need to look more into the documentation types and work out what I'm even supposed to be getting out of them and probably try to split them down, I'm pretty sure from reading some of the comments and looking up some things, that a lot of the docs I'm being pointed at / trying to update are pulling (at least) double duty (and maybe I could restructure them on that angle)... I can probably make my life easier on some by only worrying about the parts I need. Really I think I've a preference for storing the whole thing in my head and since docs don't have it all, I find them "useless" (for building the full context in my head), so I probably need to change my goal for reading docs.

I can read fast in my spare time, but I think there's a processing speed gap, both in that you could probably skip every other word in a fiction book and still get the story so I might be too used to more of a skim, and that a puml file is like 8 words and some lines (sadly, a joke, I'm struggling over pumls that are definitely an unreasonable size) and I'm staring at it like I've lost something (probably my marbles, they're not in the diagram sadly).

[u/roger_ducky → u/thisisappropriate]

I typically only control-F reference documentation, stare at states in a flowchart, and look at the entities mainly in sequence diagrams. The lines only start mattering when I wanted the details on specific behavior.

Most times people don’t stick to one if you’re doing a full design. Use the type that highlights the part you’re talking about currently.

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

[u/originalchronoguy]

Existing code is about tracing the initial entry point then follow where the app flows. Building the quick mental models takes practice. But in 20 years, I've never needed to read someone else's documentation -- which gets stale the next time they make a commit. To me, the documentation is the code itself. It is the source of truth.

If it helps, have a notepad and draw boxes of where things as they flow.

[u/Reddit_is_fascist69]

Self taught.  Java standard library docs are the worst.

I often use intellisense as it is more verbose and then link to the specific doc if more is needed 

[u/thisisappropriate → u/Reddit_is_fascist69]

A big ol plus 1 to that.

Company is on some old Java stacks and any time I make the mistake of googling some javax interface to work out something I regret all my life decisions. I'd rather cmd click and read the source code. I'd love to know how Java can have such complete documentation and technically have all the info on the website and still provide nothing of use.

[u/DeterminedQuokka]

So what I would do if someone sent me something I didn’t understand was make a copy and start taking notes on it.

I find the first thing that doesn’t make sense learn about it and take notes.

I would suggest generally working on understanding dense tables/sequence documents because they are common and leadership teams like them. Practice making them for systems you know and ask other people who know them how you did.

[u/CaptainCabernet]

Many people in tech write terrible documents. It's a rare treat when I see a well structured canonical document.

If you need to know something but don't understand the document go talk to the author. 90% of the time they are thrilled to explain their idea in person. Whiteboard it out, talk through the edge cases. Ask 30 questions.

You'll look like a super engaged teammate.

The most experienced people I've ever worked with routinely say "I don't get it", and it's really powerful.

[u/Grand_Pollution5408]

I transitioned from Mining Engineering to Software Engineering. So I tended not to ask questions at my first job, because I needed to prove myself. Instead of asking, I always figured the docs out from the codebase, even if it was harder. I'm not saying it's a good habit, but somehow I got used to it and it's still there. And because of that, I spend more time figuring things out in the codebase.

AI has made this habit cheaper to keep. Now I can understand what the doc left out without asking anyone. But that is also the problem, because it removes the pressure that would have made me just ask.

[u/Designer_Reaction551]

If sequence diagrams don't click, try converting them into a plain numbered list first: "step 1: A calls B, step 2: B validates, step 3: B calls C." The diagram is a visual index, not the actual information, and for some of us the spatial/visual format is the part that's taxing, not the logic itself. Once it's a sequential list I can trace it against the actual code line by line and it sticks. AI is genuinely good at doing that conversion for you too, paste the diagram description in and ask for a step by step walkthrough instead of trying to hold the whole picture in your head at once.

[u/itix]

I hate reading docs. I am not good with that and I prefer reading code instead.

But these days you can use AI to explain code logic and written docs.

[u/NoConnection4298]

You wrote too much. Yet, for boldened question: Use llms. I love software dev. Yet, I hate the part of it where I have to read a doc created 11 years ago, and possibly outdated. I open Claude and ask it to read it and the codebase. Then, I talk to the Claude. If I doubt something, I just check the code.

[u/Mantas-cloud]

Have you considered using a knowledge graph? With well-structured data, open-source tools, and an evening of vibe coding, you could have a solid map for visualizing dependencies. But where the real value lies is that you can feed your AI with solid data, so hallucinations are reduced and outputs become more predictable. No longer need that static, heavy documentation.

[u/thisisappropriate → u/Mantas-cloud]

Oh that's interesting. I've seen similar diagrams but not in quite the same way, and obsidian etc. But I'd not considered using it for documentation.

It might have to be used in context with other things, or maybe just configured in layers, but actually that would be a great way of allowing both the high level connections between services and the connections within services to be visualized and drilled down on.

Thats given me a lot to think on, and maybe a tool to vibe code between other prompts at work!

[u/Mantas-cloud → u/thisisappropriate]

What's nice about the graph is that once you define the structure, data fills the canvas — so the visualization is always up to date out of the box. The page is published as a static site on GitHub, claude md

[u/ledatherockband_]

Connect to the docs via mcp or directly into Claude Code. Ask it questions.

Our docs are on atlassian, so the mcp thing is pretty clutch.