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.
- No location available
-

I once worked at a company - in a different domain - that made a conscious decision to make this kind of hire. It worked incredibly well, and I never understood why more companies didn't do it.The context in my case was the Australian offices of a management consulting firm (BCG). The Melbourne and Sydney offices hired what were called "editors", brought on at the same grade as the consultants. Not editing as in correcting grammar. But helping the consultants improve the logic of the arguments in their slide decks: so they were logically consistent, easy to understand, and actually addressed the clients' issues. I was a junior consultant back then, and we were constantly pushed by our managers "have you seen Yvonne?" [the Melbourne editor] when preparing for major presentations.
- No location available
-

A previous team I was on ended up with this role. Strong writer with no technical skills joined the team and worked hand-in-hand with engineers fleshing out docs. It was productive for the engineers because they needed to articulate the ideas very clearly. The writer has been attached to that project now for 6-7 years at this point, and could probably stand in as a support engineer for some problems. It was a little painful getting HR to approve a tech writer getting paid close to an engineer position (this was after a few years).I do like the sibling comment calling for a librarian. I imagine that would pay a ton of dividends if the librarian was motivated and got support.
- No location available
-

There are three things that I think are preventing technical writing from being more widely valued:1. Software companies tend not to distinguish between technical writers who are good at English vs. technical writers who are good at engineering, understand their audience, and can articulate complex ideas to that audience effectively.2. Technical writers who are good at English make about half as much as technical writers with engineering skills, but they also muddy the hiring waters and drag salaries down for everyone else.3. Most corporate-people think because they can type up a decent email they can write technical documentation themselves. They're usually wrong on both counts.
- No location available
- technical writing,

Summary: HIGH Documentation = HIGH staleness + HIGH loss. HIGH staleness is because nobody wants to do it (status is lower). Also… nobody else can do it (full understanding of what is being documented is needed)So, to solve the first staleness part, there is only two ways: raise the documenter status, or make it somewhat possible (easier?) for someone else to do at least a part of it. are they both really that hopeless?PS: to solve the second loss/discovery part, I think we are heading for that AI powered simple "unified search" experience.
- No location available
-

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.
- No location available
-

Disclaimer: I am a consultant working for an Atlassian-centered consultancy. I do a lot of Confluence-based projects recently.You would not believe how special some use-cases are, especially when you work with organisations that have highly regulated environments. I've seen anything from markdown files in a git repository being semiautomatically created in a Jenkins run to an organization having built essentially their own wiki software because nothing on the market fulfilled their need at the time (now 5 years later, they realise no-one uses that thing because it is just unintuitive). I have seen organisations that have no content oversight and some who had a whole department of "content czars", whose sole job it was to keep their documentation fresh and updated. I've seen organisations that had strict rules on approving each individual change, with complex approval workflows.If you have never documented anything, Confluence may be overwhelming, but so will every tool that has "sensible defaults", because before too long, you will start hitting the envelope. Documentation software is not like a MacBook that you just buy and start using, you always need some level of customisation.So, is Confluence damn good? No - there's a lot that could be improved. But from the mediocre solutions on the market today, it is one of the better choices.
- No location available
- wikis, confluence, documentation, organizational infrastructure,

The issue with wikis (not just confluence) is there's no approval or review workflow. Imagine trying to write a large program in which everyone could just commit at will, with no review process whatsoever, and where nobody had made any decisions about design up front. There'd be duplication, dead code, the organization would be crazy. That's the average wiki. It's a commons and a tragic one. To make docs work you have to treat it more like a codebase: clear ownership, standards, review processes, approvals, up front design, refactoring efforts etc.
- No location available
- favorite, wikis,

the use case for Google Docs is somewhat different in my mind. It's good for collaboration and discussion, rather than a source of truth to describe "how things are right now". It's annoying if you can't find a particular document immediately but it's not the end of the world. Discussion on a Google Doc will happen for a few weeks or a quarter, then die down and the doc will seldom be looked at again. You might link to it from tricky parts of your codebase but it's not essential to a high-level understanding.Confluence and other wiki systems are clearly meant for longer-lived documentation and canonical information. You should link from or attach your working documents (spreadsheets, slide decks etc) to your wiki documentation for people to discover why certain decisions were taken. But if the wiki's discoverability is poor or it's not well-maintained or regularly reviewed, it's basically useless.
- No location available
- organizational infrastructure, favorite, knowledge management, wikis,
- [note::This supports the notion that organizations should have two separate knowledge repositories: a continually maintained wiki like Gitbook and a knowledge dumping ground like Google Drive.]

Not a fan of Google docs either, but I recently discovered CloudSearch which imo does a better job at searching Drive (and searches emails too, and few other places).link: https://cloudsearch.google.com
- No location available
-

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
- No location available
-

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.
- No location available
-

Documentation has upkeep costs as the software and environment change.
- No location available
- documentation, upkeep costs,

> 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
- No location available
-

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.
- No location available
-

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.
- No location available
-

I'm convinced that documentation, even for large companies, should just be an Obsidian vault of markdown files maintained via git which is just rendered on the web either using a simple static site generator or using Obsidian Publish. When I brought this up at my last company it got dismissed as being 'too technical'.
- No location available
-

> I know git can be tricky but it cannot be that difficult to teach people from non technical departmentsThis is far more difficult than you're suggesting. Git still confuses a lot of junior and mid level devs the second anything deviates from their memorized command workflow.If you're expecting non-technical people to have to learn git just to edit the documentation, they're just not going to use it at all.Writing and aggregating good documentation needs to be easy and simple. Gating documentation behind git is the opposite of that for non technical people.
- No location available
-

Or just download Github Desktop onto their machine and show them how to use it.
- No location available
-

> This is far more difficult than you're suggesting. Git still confuses a lot of junior and mid level devs the second anything deviates from their memorized command workflowGiven the number of non-programmers who Really Need the functionality of git, who probably won't be able to hack dealing with it, doesn't this indicate that there's some huge vein of untapped value to be won by whomever cracks the problem? (Version control for business people?)
- No location available
-

GitHub wikis or something similar can work well as an in-between option: edit in browser or git clone, whichever is easier in your context.https://github.blog/2011-01-17-
- No location available
-

GitHub wikis or something similar can work well as an in-between option: edit in browser or git clone, whichever is easier in your context.https://github.blog/2011-01-17-git-powered-wikis-improved/
- No location available
-

There are Wiki-like interfaces for git+Markdown: GitHub's wikis, gitit, and more
- No location available
-

I'm a CTO in a startup and all our docs are in .md files, mermaid diagrams with dynamic Table of Content generation.We have two repos: Product (to anything relating to product) and Wiki (anything else, ranging from onboarding checklists, brief design documentation of key parts of the code ... to meta documentation)Although our team is small by many standards (8) everyone likes it.We spend a ridiculously small amount of time on meetings.The obvious and great upside is the code/documentation integration which has virtually 0 context loss.One downside however is indeed the difficulty of git branching to non-developers.Once in while I find myself debugging a messed up version.But I'm willing to pay that price.
- No location available
-

I wouldn't even bother with the static site generator. While I like the idea of STGs, in my opinion, they all suck. And now there has to be someone to maintain how those pages are rendered and know how whatever thing like Jekyll works.Just let developers either read the markdown files as-is or set their IDE to render markdown previews by default. I prefer the latter because I don't have to wait for someone who's on vacation half the time to render the latest docs.
- No location available
-

When it comes to API documentation, everything should just be inline comments in the doc format of choice for the team. Don't bother rendering this out, because every flipping tool ever invented for converting inline documentation into HTML fails on something simple. Developers can read the inline docs as-is and/or rely on their IDE to provide them hints from those docs.
- No location available
-

If you have to deploy your documentation, that's how you know you might as well give up. It's one thing to deploy documentation for 3rd parties, but for documentation being used internally there's few good reasons to turn the documentation into its own website. That's extra work that I've never seen increase productivity or developer happiness. Don't put documentation behind one or two guys with special permissions to press a deploy button. If you do, the documentation will always be out of date as soon as it's rendered.
- No location available
-

Remove as many reasons that devs won't write documentation as you possibly can.
- No location available
-

I don't like Confluence either, but the platform is only 10% of the problem. Knowledge Management platforms are something that PMs love to debate, purchase, and use to get promotions. So you end up with a company that has 6+ platforms. This is way worse than having one unified, crappy-UX, wiki.Finding the perfect documentation platform becomes a waiting-for-superman game. Everyone loves to complain, but nobody wants to put in the actual work to write clear content, define information structure, consider audience, etc.The real solution is hiring people who are excellent writers. To do this, leadership must be good at reading and writing themselves (not a given) and be able to recognize top contributors.
- No location available
-

> I'm convinced that documentation, even for large companies, should just be an Obsidian vault of markdown files maintained via git which is just rendered on the web either using a simple static site generator or using Obsidian PublishThis, except for normals, sort of exists:Craft: https://www.craft.do/solutions/businessesDefault is internal only, but you can allow sharing, which creates a web URL that can be privately or publicly shared (and can be on your own custom domain).It has versioning, it has comments, it has real time multi-editor collaboration. An entire conference room, in person and virtual, can co-edit in true real time without anything blowing up, a feat not to be tried in Word, or even Google Docs.Most firms should stop looking and just try Craft. Encourage everyone to do everything there, see what happens.Note bene: it happily imports markdown, also exports Word, PDF, Markdown, and Textbundle, and can feed a static site gen.They also keep busy: https://www.craft.do/whats-new// I use Obsidian for myself, but Craft to collaborate with non-engineers. I've also been known to recommend FOAM to engineering teams, coupled with mkdocs and a good theme for static site gen, such as material for mkdocs:https://foambubble.github.io/foam/https://github.com/squidfunk/mkdocs-materialFor eng teams already living in VS Code, it's hard to beat PKM where you already are.
- No location available
-

This is what the Gitlab wiki does. There's a markdown+git interface for technical folks and a web interface for normal people.
- No location available
-

Does using Git contribute anything of value to the documentation that you could not possibly get without git?The answer is, of course: no. You just want it because it's familiar to you. Which is fine... if you were the only person using it.Confluence is actually the best solution, hands down. It has a WYSIWYG. It supports Markdown. It has an API. It versions all content. It has fine-grained access control. It does not require granting a user access to a repo to write to a file. It has much more rich content to better convey information clearly to humans. It has full text search. Page management is simple (rename a page and it auto-redirects). And no other solution does all of this as easily or effectively.The people who complain about Confluence simply don't care about use cases outside their own, and haven't taken the time to learn it. I am 100x more productive with Confluence than you are with Git and Markdown. And real people will actually be able to use what I've made there without learning complex tools or jumping through hoops.
- No location available
-

Hadn't heard of this before, looks very cool. For anyone interested: https://github.com/claudioc/jingo
- No location available
-

There's Gollum, which powers the built-in wikis on GitLab and GitHub. Its web UI handles making commits for you.
- No location available
-

GitLab employee here. This page of our handbook can be a good starting point to build your own: https://about.gitlab.com/company/culture/all-remote/handbook...
- No location available
-

Git is not that complicated and this may work for purely internal software docs. But good luck scaling your org, working with customers, investors, vendors etc and not ending up with at least done MS office documents and email as the only record of what is the latest version.
- No location available
-

I don't think documentation is a problem with a technical solution - it's an organizational commitment and incentives problem.
- No location available
-