[canucklady]

My current employer was sold to me as a "high documentation" place. What it means in practice is that if you're trying to do something there are 5 outdated documents describing the decision making process for how the project was run, and no documents about how to actually use the resulting software. Occasionally if you ask how to actually do a task in Slack someone will yell at you that you should have searched for a specific, obscurely named document in Google Drive, Confluence, or Github. We've tried a bunch of search tools which successfully surface the million product documents, design documents, PM reports, planning docs, retro docs and standup and oncall notes related to any feature, none of which are up to date.

[ebiester]

I would suggest introducing two things.

First, introduce The Diataxis framework ( https://diataxis.fr/ ) for documentation. It makes people think about documentation in a more structured way, and allows you to be more specific in the types of missing documentation. (High documentation cultures are often good with explanation but not tutorials, for example.)

Second, I would introduct the idea of a Documentation Portfolio. I have a review of Agile Documentation at https://www.ebiester.com/documentation/2020/06/02/agile-docu... and it speaks to another structure for how to build the documentation in a more reliable form and thinking more carefully about your audience for a particular type of documentation.

[mr_gibbins]

I'm sure these are great technological answers but this problem can be solved simply and quickly by a human.

Not every issue needs to be solved by a butter robot.

Why not employ a technical writer/documenter/whatever job title you like, even as a temp, whose sole job is to sort out the mess of documentation you have and then to write new documentation as you move forward?

[FooBarWidget]

What's the difference between Diataxis and the Divio documentation framework? https://documentation.divio.com/

[crazygringo]

Diataxis looks fantastic. That chart on the home page is absolute gold.

Thanks so much for the link, I wish I'd had that chart ten years ago!

[q7xvh97o2pDhNrh]

Whoa! I love a good 2x2, and the one on the Diataxis home page is great!

Adding a caption here for anyone on a screen-reader, before I give commentary on it:

  * X-axis: "serve our study" vs "serve our work"
  * Y-axis: "practical steps" vs "theoretical knowledge"
  * which gives 4 quadrants: how-to guides, tutorials, explanation, and reference

So I'm joining a new place recently, and it's another one of those "documentation-heavy" places where (of course) every new hire conducts the ceremonial ritual of updating the docs wherever they could use improvement. I really like having this ontology in my head now; I can see it being very useful.

Also, I wonder if the relative distributions of each one could tell you something about the team's health — or even just the kind of work the team does?

For example, between two teams who are both documentation-heavy, what does it means if one team's docbase is 80% tutorials, whereas the other team's is 80% reference guides? It would be fascinating if anyone's already given thought to relative metrics/heuristics like this.

[c54]

Diataxis looks interesting thanks for the link

[lliamander]

The diataxis seems quite interesting.

I see how it applies to documents which describe things as they are, but I'm curious how it would classify forward looking documents like technical designs, strategy and vision documents, roadmaps, and mission statements.

[throwaway290]

This does not help with outdated docs.

[triceratops]

> Confluence

There's your problem. The only use case for Confluence is when you want to hide information, but credibly claim that it's documented.

[PragmaticPulp]

Confluence (and all of the similar products) can be used successfully, but you need the teams to agree on and enforce a logical document hierarchy. It’s not really difficult to organize a company wiki into teams, projects, and other logical divisions if you make it a priority.

The primary failure mode I see is when people just throw random documents into Confluence wherever convenient at time of writing and never go back to logically organize anything. One symptom of this is when key information is being recorded in a hundred different people’s “Personal Space”

Taking even half a day to organize the average Confluence makes a huge difference.

[cmdrriker]

Does it matter what tool you use to write documentation? Confluence gets a lot of sh*t because its in the grown-up camp of tools but I know people who've got problems even with nano.

It's incumbent upon all users or members of the team to use the common tool along with agreed upon standards. Otherwise even if you wrote documentation in your own hemoglobin, no one would touch it either.

Some manager prob chose _________ as the tool for ticketing, documentation, etc not because it was good at ______, or _______ but because it fulfilled their action plan to have something, anything in place so that if the universe goes supernova, well some stuff was written down.

In my journey it seems that nobody is willing to criticize Edward Teach for the lousy treasure map he left, but rather we make fun of those who're still looking for his stuff.

[fsociety]

Ha I hear this a lot but the alternatives I have seen used are frankly just as terrible. I much prefer Confluence to a hidden web of Google docs.

[Macha]

I'd take confluence over google docs because of how bad Google Docs' search is surprisingly

[SAI_Peregrinus]

We use Mark[1] to automatically create Confluence pages from Markdown documents in our git repos. So we can have a review process for documentation changes, the documentation of the code can be in the repo with the code, and yet it can still be accessed without having to give permissions to view the code repo! Helpful with a proprietary monorepo.

[1] https://github.com/kovetskiy/mark

[schnitzelstoat]

Yeah, the search function in my company's confluence is abysmal.

There have been times I know a page exists and I even know the title/content of the page and yet still I am unable to find it via the search.

[EFreethought]

> The only use case for Confluence is when you want to hide information, but credibly claim that it's documented.

That describes Sharepoint more than Confluence.

[balaji1]

Did I miss it or does the article specify what tools Tremendous uses for their documentation?

[roflyear]

Yeah, I push back when people say "can you document that API you wrote in confluence?"

It is such a stupid idea that it makes me question leadership.

Some things are good to document there, but generally, if you're documenting code, you should do it in the code.

[arendtio]

So which tool do you like?

[satisfice]

I will say the obvious: documentation sucks because good writing is a highly skilled activity that takes a lot of energy for most people to do, AND because keeping it up to date takes a lot of time, no matter how good you are at it, AND because leaders of companies don't want to spend ANY money on tech writers.

That's it. No mystery.

(BTW, this would also be why company financial records would suck, if management decided to save money on accounting staff and have all employees just kinda do their own accounting for the company. I SAY HIRE A SCRIBE FOR EVERY TECHNICAL TEAM!)

[arendtio]

> good writing is a highly skilled activity

This. Yes, having everything written down and searchable is definitely a good goal. However, in my experience, the people in most companies have very different skills and few are good writers. So it probably takes a lot of time to create an organization that has a good process for creating great documents, let alone to transform an existing organization which can do so.

[bakuninsbart]

Ironically, it is much easier for me to write good documentation if there are a couple of meetings scheduled around it. Having 3 joint sessions with at least another person is great, first to get the "bone structure" of the document, then to confirm that the "flesh sits right", and finally to resolve any unclarities that might be left.

[wpietri]

I think it's important to realize that a lot of documentation is duplication. It duplicates something expressed in code, in configs, in structure, in people's heads, or in the real world.

Duplication can be useful. But the more of it you have, the greater the maintenance burden is. (The main exception is documentation that is not supposed to be kept up to date, like a daily journal or blog posts.) So I think it behooves people to be very careful about adding documentation. Because as you say, it can turn 1 problem into n problems.

[gmd63]

No, code actualizes the intent of the documentation and the product. The natural language description of a product shouldn't need to be discarded in lieu of some machine language.

The lingua franca of ideas is natural language.

[futureproofd]

Do we work for the same company? :P

Confluence has been the bane of my attempts in finding any relevant docs. Which one is the source of truth? Which one was a draft written by an overly eager to make a first impression, new employee (who is no longer with the company)? Don't even get me started on saving meeting notes to confluence.

These days, I maintain my own knowledge base on Obsidian. If there's ever any confusion or request for more information within the company, I copy-pasta the relevant note from my obsidian bank to whomever person or whichever confluence page they deem the source of truth.

[nopenopenopeno]

Do you have any tips on how to maintain a developer's own knowledge base in Obsidian? I also use Obsidian but I currently use as more of a dumping ground.

[chocolatemario]

I do the same except in org mode. I’ll export to markdown as needed but generally publishing documents is a secondary goal to empowering and decreasing the burden on myself.

Design docs for each and every feature has turned out not to scale for my current team. Larger, multi team features demand consolidated documentation, but for internal changes we rely on quick meetings as code reviews. Part of me misses the ceremony of the round table discussions, but the real difficulty is keeping track of why changes happen. Documenting processes and cross cutting concerns is a must have, but keeping track of all changes across quickly moving teams… it’s no surprise so many teams are just rife with tribal knowledge.

[neura]

So you are now the gatekeeper?

[hw]

What many dont realize is that documentation is tech debt. You can spend a lot of time and write a lot of documentation and have to also spend time updating it.

I have worked with teams that focus so much time on design docs and insist that everything has to be documented. Pace of work is slow. Documentation and designs became obsolete due to shutting down of services, change in architecture, refactors.

The best form of documentation is code.

[tshaddox]

I think it’s a bit odd to call it tech debt. I’d say something more like “documentation is part of your tech, and needs to be maintained like the rest of your tech.” It’s only tech debt if you decide to not maintain it.

[dnsmichi]

> The best form of documentation is code.

Documentation as code might be a good alternative path, using the same tools and processes as software development and embed documentation tasks into engineering workflows. More insights in https://about.gitlab.com/blog/2022/10/12/five-fast-facts-abo... how the GitLab technical writing team collaborates.

Note: GitLab team member here.

[scottlamb]

Yeah, that sounds horrible yet familiar. Regarding this part:

> Occasionally if you ask how to actually do a task in Slack someone will yell at you that you should have searched for a specific, obscurely named document in Google Drive, Confluence, or Github.

When I'm the person being asked and know of the doc in question, here's what I try to do instead: I ask where someone searched for it. Then I update that place to refer to the correct document (and do some light refresh on the doc as needed). This works whether or not they tried to look before asking. If they did, well, now the next person who does that will just find it. If they didn't, I'm making them look before getting an answer. Maybe they find it, maybe they don't, either way I'll help them in the end if they're willing to look.

[synu]

You really have to be religious about enforcing a single source of truth for any information and this gets a lot better.

[gautamdivgi]

There are docs and then there are Docs. I think documents should be treated as source code. Go through a proper PR process so that you know what the latest and greatest is. Maintaining a wiki is one of the worst ways to document. It just creates a sprawl that is hard to control. I deal with it on a daily basis but have had little success with getting my team moving to our source control system for documents.

[sdflhasjd]

It's actually hilarious how Google - a company famous for it's search engine - made Docs, who's search function cannot find anything.

[crazygringo]

I live and breathe using Google Docs search functionality. It's my main way of finding files scattered across 10 years of folder hierarchies. It works great.

What do you mean it can't find anything?

[jumpei163]

Are you using search feature in Drive? I've been using CloudSearch, which I heavily rely upon

[mnd999]

And it’s still miles better than Confluence.

[rqtwteye]

I work in medical devices so we have to write a lot of docs. But they all disappear in document management systems where you can't find anything if you don't already know where it is. Are there no document management systems that are actually useful?

[wpietri]

Ask yourself how many document management systems are selected after rigorous tests of actual usage vs those selected after sales presentations and schmoozing. That should give you your answer.

And if that's ambiguous, then ask how often your company penalizes people for making the common but wrong choice versus the uncommon but wrong choice.

[yamtaddle]

A good secretary (or a bunch of them) and filing cabinets.

You may still not know how to find anything, but they will.

Like a lot of other things, this has suffered from computerization making it yet another small part of everyone's job (which also increases context switching, the amount of shit you need to know and keep track of, and generally makes jobs more stressful) rather than a specialty that's the main focus of a few workers.

The benefit (get to stop paying some employees) is easy to measure, while the harm is not.

[contingencies]

git works for us across business/electronics/electrical/mechanical/software.

The exception is daily supply chain and accounting, which due to factors like urgency, multiple stakeholders per order, high pace of handover, external system integration, multilingual presentation requirements and nontechnical users we prefer a dedicated web based system with more of a real time focus with event hooks (eg. notification, translation, verification).

[baby]

Sometimes (often?) an outdated document is still great and useful and much better than no documentation at all

[zeroonetwothree]

Equally often it’s worse and a waste of time. And you won’t know which world you’re living in for a while.

[BurningFrog]

Everyone wants accurate updated documentation.

Nobody knows how to accomplish this.

Whatever the solution is, if one exists, I'm sure it involves a lot of work keeping documentation up to date.

[TylerE]

They know how (documentation is embedded in/generated from code) they just don’t want to.

Out of date doc is worse than no doc, because it makes you feel all warm and fuzzy right until you footgun.

[nonethewiser]

> My current employer was sold to me as a "high documentation" place. What it means in practice is that if you're trying to do something there are 5 outdated documents describing the decision making process for how the project was run, and no documents about how to actually use the resulting software.

How is this not inevitable if your goal is to always write things down? It seems like the way for document to be accurate is to keep the scope small and if you want everything in scope then it's going to contain a lot of outdated information.

[ghaff]

You basically need to deprecate and eventually probably take offline outdated docs. There's something to be said for the historical record but if it's indexed--and if it's not no one will probably find it--it's going to compete with current documentation for search.

There's no easy answer.

[apatters]

So update the documents?

I mean, you're clearly not describing a high documentation culture, you're describing a culture that underinvests in intra-organizational communication.

I run a high documentation, low meeting culture by necessity (we operate in five time zones around world). Meetings vs docs is remarkably similar to the decision between paying for office space vs paying for occasional team retreats. If you run a fully remote company retreats are almost always a better use of your money than leasing office space. But you still need to pay for something.

Similarly with meetings vs. process documentation. If you're heavily remote and spread out I'd say you should cut down on meetings and being high documentation is the better choice. But again you still need to "pay" for something - you save time on meetings but you need to reinvest at least part of that time into writing documents.

Another bonus of documents is that they scale better than meetings. McDonald's doesn't deliver the same big Mac in every corner of the world by holding a lot of meetings. They have a book that goes out to all of their thousands of franchisees. When they want to add another thousand franchisees, they print more books.

If the documents are out of date my answer to my team is always "update them!" Anywhere that we're writing documents there are revision and discussion features so it's not like you can irrevocably screw something up, just improve it and let us know what you did. I do struggle with getting people to actually do it though.

[nelsonic]

Having multiple systems for docs and Slack for follow-up questions is a major red flag. What you’re describing is a billion dollar search product opportunity though. Most orgs don’t have the discipline to have a single source of truth. So you end up with this mess. Run! Or … fix it and then create a company to fix it for all the other orgs with similar data/docs siloes.

[pokstad]

I don’t understand why more companies don’t just go all in on Slack as the interface to their knowledge base. There’s tons of integrations to enable it. Every place I’ve worked at with Slack has the standard 90 day retention policy in place which makes it impossible.

[dougk16]

One solution to this is to become an oracle at your company. Any time someone (namely someone higher in the company who is responsible for your pay) has a question, no matter how many times it's been asked, how recently it's been asked, how obvious and repeated it is in the documentation, you answer quickly and thoroughly, like a machine. After a year or two of this, you'll be able to ask for any raise, or to work remote, or to even switch to contracting. They won't want to lose you.

[ramesh31]

This is why I find documentation to be either useless or actively detrimental. Your documentation is the code. Unless you have a dedicated technical writer on the team whose full time job is to work with developers to document their code, it all just becomes an outdated confusing mess immediately.

Obviously this doesn't apply to public facing codebases. But trying to keep an internal codebase documented, other than fully finished self contained library level code, is a sisyphean task.

[atom_arranger]

Agree. If possible the documentation should live in / be generated from the code as well.

I'm not checking confluence, write it in a ".md" file in the repo if you want me to see it.

[convolvatron]

that's ok. but expect your onboarding to take a really long time.

[narrator]

The way I did this at a company I worked for is that we had a MediaWiki. That's the software that runs Wikipedia. Whenever anyone would ask me a question, I would make a MediaWiki page or add to an existing page and appropriately link the page or entry to other relevant pages and answer the question there. Then I would send them a link to the MediaWiki page. This was super efficient. Whenever any documentation was wrong, I would update it.

[jollofricepeas]

Exactly this.

I think that high documentation can work BUT the company has to invest in it in the way that Digital Ocean or even Stripe has done outwardly.

1. Investment - You have to hire at least a few technical writers and librarians to provide training & cleanup functions.

2. Management buy-in - You have to budget for it and encourage it through day one communication (ie. New hire training) and consistently rewarding and recognizing people for getting it right.

[jmspring]

One of the biggest issues with large companies is - there could be a lot of documentation- but can you find it.

A lot comes from tribal knowledge/who to talk to/etc.

[civilized]

From my perspective, calling yourself a "high documentation" org leaves a similar impression as calling yourself a "high code" org.

[coffeeblack]

Very much my experience too.

People need to actually learn how to write and maintain(!) documentation, otherwise it’s just a huge chaos.

Rule 1: less (text) is more.

[commandlinefan]

> 5 outdated documents describing the decision making process

Would that place be the U.S. Department of Defense by chance?

[rfdave]

Not if there's only 5 documents.

[EFreethought]

> you should have searched for a specific, obscurely named document in Google Drive, Confluence, or Github

Are people at the same job telling you to check 3 different sources for internal docs? Maybe that is the main issue. Put knowledge in one place.

More specifically: One place that is not Sharepoint.

[stirfish]

> no documents about how to actually use the resulting software.

Can all your engineers see all your other engineers' code? It's hard enough to get code to do what it says it does; I've very rarely seen documentation that's correct.

[gmd63]

Lack of organization to that degree is an indicator of failed leadership

[xlix]

This sounds so similar to my new place of employment, it has to be the same.

[znpy]

We might be colleagues then.