Do you have a documentation strategy
Posted by lambda-reddit-user@reddit | ExperiencedDevs | View on Reddit | 29 comments
Hi everyone,
I joined a new squad 2 years ago and I realize there that documentation was not really optimal. We have a very huge scope and today we have everything on sharepoint with no real way to go through it, just a lot of docs there and you need to find out where to start and where to go next.
I would like to have a real strategy for documenting with structure and more important a flow so that new joiners can find their way very easily
I’m wondering how some of you do manage this where you work ?
flavius-as@reddit
I'm a big fan of executable documentation and written documentation to show the breadcrumbs between these pieces.
That's stuff like unit tests (with a correct definition of unit, not "a class" or "a method"), sql views, monitoring dashboards, models (think sparx ea) with strong traceability.
Reptile1712@reddit
What is your definition of a unit?
Unit definition is one thing I always have to (unsuccessfully) fight since unit testing is increadbly KPI driven in safety environment. I always preferred more broad guideline of ISO 26262 that it is a smallest part of software architecture that can be tested standalone.
flavius-as@reddit
"Method" is correct, but it's not fully correct. Ultimately you do test methods. The detail which most definitions of unit testing misses is: the level of abstraction at which the method is positioned in the call hierarchy.
How those methods are defined highly depends on the architecture of the concrete project.
I usually make domain-centric architectures with hexagonal as a backbone and elements from clean, DDD and other styles and patterns.
In my architectures, those public methods which are units of behavior are:
diablo1128@reddit
What is wrong with class level? Everywhere I have worked had unit tests at the method level and I always though it was too low. I feel like class level makes sense you should test your classes using the public methods and excepted / unexpected use cases.
This was in addition to integration testing, which were to software requirements at the subsystem boundary level.
rcls0053@reddit
Not a strategy for the org or team, but I myself believe in what researchers discovered at Google. They noticed that the best model is to write documentation in the source code repository and simply pull it from there into other places if needed, such as a combined documentation portal or smth.
tikhonjelvis@reddit
Oh man, I've believed this based on my own experience for ages, but have had trouble convincing others. I'll have to track down the research so that I have a legible reason for my preference in the future :P
Ulfrauga@reddit
So the guts is based in .md files, and how you display it or use it varies - in the repo itself, or pulled into some web page or similar?
Nice idea. I'll give that a go. Where I am there's basically no standards or anything for code documentation. Whatever we feel like 😬 I've come to the conclusion Word documents in SharePoint aren't quite right for everything.
EducationalAd2863@reddit
Pretty much backstage :)
ThlintoRatscar@reddit
Do you have a link to that research?
throwaway_0x90@reddit
Google engineer here,
It's done like github; we have README.md files in the source repo and there are internal webpages that can pull the .md files from the repo and display it in your browser all pretty-like.
Just like github.com, with maybe a few other bells & whistles to make things nice for us.
ThlintoRatscar@reddit
Sweet!
We came to a similar conclusion a number of years ago, but I wasn't aware of any academic research that supported or discouraged it.
Thanks a ton for that Abseil link!
Cold-Dare2147@reddit
I’ve seen this in practice at one of the food delivery apps. There’s 200 repos. Each have their own docs. Then there’s a job when things get merged to update this static website that contains the docs for every repo.
wimdeblauwe@reddit
I wrote a blog post about this: https://www.wimdeblauwe.com/blog/2025/09/08/how-i-document-production-ready-spring-boot-applications/
chrisza4@reddit
Here is the best talk about principle of documentation as far as I have seen. Still using this principle to this day.
https://youtu.be/t4vKPhjcMZg?si=0mLFZq_BbttlZQxg
Abadabadon@reddit
Confluence and inline doc with everyone having read access on gitlab, you can easily search for your solution
kyledag500@reddit
We use confluence from atlassian. Their AI is able to scan your wikis and find you what you’re looking for easily.
MoreRespectForQA@reddit
For new joiners I feel like documentation is a bit of a waste. I will usually just pair program with them until they are up to speed.
It's a waste because:
You are trying to anticipate what they want to know but will probably miss the mark. Whereas if they are there they can ask questions directly.
The documentation will probably have gone stale by the time the next person onboards.
It's still worth maintaining docs for things like getting the repo up and running which they might use multiple times and people outside of the team might also use.
Bobby-McBobster@reddit
Yeah. Read the code.
Feinberg123@reddit
Shut up
logicannullata@reddit
Good that you are exploring ways to create better documentation. Many already gave you suggestions on how to do that. My advice is to focus on documenting the right things, I see many new joiners (seniors and juniors) trying to document everything, that's an anti pattern because then you have to maintain that documentation. Prioritize the important stuff, I am kinda annoyed by readmes of Python projects telling you how to install python, at some point you should assume a minimum level of knowledge from your audience.
razzledazzled@reddit
We recently converted to using a docusaurus project hosted on github enterprise for documentation. This is an area where I've found AI to be a big help-- I use prompts to create all the fancy React components to help better visualize the information I'm trying to share.
The git-based solution solves a lot of other problems with stuff like Confluence in a way developers already understand. And projects like docusaurus give it a really nice looking presentation layer to play with.
dethstrobe@reddit
Tests.
I’m actually working on a reporter for playwright that turns e2e tests into to docusaurus markdown. So literally your tests are documentation for non technical stakeholders.
Test2doc.com if you want to check it out.
maulowski@reddit
I’ll let you know when I figure it out. 😅
But for now, yes, the goal is to keep things in the /docs directory and use Copilot to read through classes, draw sequence diagrams, etc. The main ReadMe doc will contain information about the repository and the app as well as links to the docs folder.
Rain-And-Coffee@reddit
I created most of docs for my team
Tried a variety of different formats, from Wikis, Confluence, Markdown sites (like MkDocs).
I prefer Markdown embedded in the repo.
drnullpointer@reddit
> I realize there that documentation was not really optimal
Haha;-) You will get far...
> I would like to have a real strategy for documenting with structure and more important a flow so that new joiners can find their way very easily
Sure. Here is mine.
I created a checklist of everything that needs to be verified at code review time.
One of the checklist items is that it is prohibited to merge code without director approval if the code changes any externally observable behavior that is documented. Also, any externally observable behavior needs to be documented. The only difference between the two is if there is a bug in the code that makes the application behave differently than the documentation. In which case it falls under the case where it changes the externally observable behavior that is not documented.
Anyway, if somebody wants to merge anything that does not meet this requirement they need to obtain my approval and I simply don't give the approval.
flowering_sun_star@reddit
I wish!
I've come to the belief that documentation external to the code might as well not exist. It can be fine for the duration of a project, but after the project is done it will slowly rot.
The most reliable documentation we have is for APIs. Some of that is through OpenAPI docs that are used to autogenerate interfaces for use in code, with a formal review process for any changes. It's a fairly heavy-handed approach, but it makes sure that changes don't happen with corresponding documentation updates.
Code comments on individual code blocks with the business reason for that bit of logic tend to be both unlikely to rot and useful when doing investigations. Tricky to persuade people to bother though!
But both of those cases are where the documentation is closely attached to a single point. Documentation of wider behaviour of the system is much harder, and I don't have a good answer yet. As soon as you can make a change without seeing that the documentation is outdated, things will start to rot. Perhaps this is something that LLMs could be good at - could we design an automated process where an AI is instructed to review whether a change breaks anything in the docs?
ViiiteDev@reddit
I co-locate docs with code in /docs folders within repos. I let Claude maintain/update these markdown files whenever we make changes - it keeps architecture decisions, setup guides, and API docs current with zero manual effort. Bonus: it gives Claude full context for future sessions since everything’s in the repo.
Adventurous-Date9971@reddit
Co-locating docs with code works, but add guardrails so AI edits don’t drift. Require CODEOWNERS on /docs, run markdownlint/vale and lychee link checks in CI, and block merges if src/ changes without docs touched. Keep ADRs via adr-tools, and have a “Start here” index per repo plus a cross-repo map for OP. Generate OpenAPI and diff it in CI; Redocly for publishing, Stoplight for mocks, and DreamFactory when I need instant REST over SQL so agents can test. Guardrails plus CI checks keep repo docs reliable.
qpalzmg@reddit
A team repository for all the docs to sit in.
They can range from a very general onboarding doc that u can point to new joiners on their first day to very nuanced step-by-step guide on how to do something.
Remove as much resistance as possible such that any one can contribute at any time, and don't have to think about where to put it.