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 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.
Try explaining that they can't push to the repo because they cloned the http URI and need to generate an RSA token and use SSH instead. Better yet, try to figure out that's the problem when they give you a totally unhelpful version of what the problem is.
Another not great but possible solution could be for non technical people to work on something like a Google Doc when stuff is in highly active development and to then copy this to a markdown document later when its solidified.
I do think that as a society we have to start looking at stuff like this as a new essential skill though. We wouldn't expect people to be working without basic literacy, numeracy and computer skills and I think we are going to have to start looking at upgrading our sense of what basic computer skills entails to include stuff like git and teaching it in schools from an early age.
And related to this is the state of WYSIWYG markdown editing.
The Basecamp folks created the very polished Trix rich-text drop-in which is a replacement for TinyMce, which while the standard seems to carry issues.
Basecamp explained the issue with most approaches as such:
> Most WYSIWYG editors are wrappers around HTML’s contenteditable and execCommand APIs, designed by Microsoft to support live editing of web pages in Internet Explorer 5.5, and eventually reverse-engineered and copied by other browsers.
> Because these APIs were never fully specified or documented, and because WYSIWYG HTML editors are enormous in scope, each browser’s implementation has its own set of bugs and quirks, and JavaScript developers are left to resolve the inconsistencies.
> Trix sidesteps these inconsistencies by treating contenteditable as an I/O device: when input makes its way to the editor, Trix converts that input into an editing operation on its internal document model, then re-renders that document back into the editor. This gives Trix complete control over what happens after every keystroke, and avoids the need to use execCommand at all.
Unfortunately Trix does not render markdown so can’t be used in a markdown documentation workflow.
Has anyone seen a decent implementation of WYSIWYG for markdown that has the necessary polish to be non-tech friendly?
https://discuss.codemirror.net/t/implementing-wysiwyg-markdo...
It's ok to be technical and not enjoy markdown, heh.
As much as I hate to admit it, sharepoint works better here.
On the upside for Google docs, commenting and edit suggestions work so well it’s become easier convince people to use Google docs without downloading copies.
How do you find a happy medium between this and a Confluence-like free-for-all, where anyone can create/edit a page?
But yes, the out of date info is a killer.
Given 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?)
I'm going to take a slightly different interpretation of your comment because I think it's an interesting discussion: are the non-technical people of today less technical than the non-technical people of the MySpace days?
From what I have observed, I would say yes. If you took the bottom 10% of users back then, you might have a hope of teaching them HTML. Today? No chance. In particular I think "willingness to learn anything" has really waned.
If there are more of them now it's probably because computer use expanded 100 fold since then, at least, and the largely self-selected 90s users of the Web, especially, tended to have greater-than-average interest in learning computer crap, so a high proportion of new users were the can't-or-don't-want-to-learn sort. In the 90s a computer still might not be the centerpiece of an office worker or middle manager's desk, and most folks used computers very little at home, if they even had one (data I'm seeing indicates % of households in the US with a computer only hit 50% in 2000).
And dealing with merges that involve only documentation in Markdown is similarly totally doable.
But then for actually releasing the docs, or tying them to feature commits etc., that all has to be done by actual devs. Also the creation of branches.
Also, people working on documentation in a software company aren't exactly "non-technical". They might not be full engineers but they can definitely handle files and some light version control.
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.
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.
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.
Remove as many reasons that devs won't write documentation as you possibly can.
The documentation for almost every public Rust library is automatically rendered and hosted on docs.rs and it's incredible to have that consistency.
Just check out this Regex type and the awesome documentation for every method, all taken from inline comments:
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.
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.
2. Write .
It's not that hard really is it.
At the end of the day, if you've got someone who can't work out how to drag a file into a folder and then type  after you've shown them a couple of times, is this really the person you want writing the documentation for your process?
This makes no sense given that you get the same payoff by using something like Atlassian's wiki. No git, no markdown, none of this nonsense, users can just immediately hit the ground running with advanced formatting support and version history.
I think you're lacking a lot of empathy for nontechnical users. I don't see how you could ever argue that your git + Obsidian stack is "more valuable" than an off-the-shelf wiki solution.
I have empathy for non technical people in that I believe Markdown is far easier to use than Atlassian's interface. Every single developer I've worked with has been tearing their hair out when trying to write documentation on Confluence and documentation never got written as a result. If this is the experience for technical people, what on earth is the experience like for non-technical people?
Nobody cares. Really, they do not. This doesn't help the business, it adds way too much overhead, and requires nontechnical people to understand markdown and git.
I have never heard nontechnical people complain about the Confluence wiki. From their perspective, everything Just Works. Imagine having to tell them all the things that they can't do because of Markdown's limitations, and how much harder it is to do drop-dead simple things like adding tables. Can't you see how that's a 100x higher barrier than anything you can complain about for Atlassian? Anything that you're frustrated at with their editor, you probably can't even do in Markdown. All the markdown stuff is easy.
They absolutely care if one day Atlassian decides to hike prices to levels they deem unreasonable and now their entire documentation is locked in a proprietary format or if Atlassian go under, are purchased by a competitor etc.
> I have never heard nontechnical people complain about the Confluence wiki. From their perspective, everything Just Works.
This has not been my experience at all. I've had tons of business analysts join in the Confluence moaning during meetings, both for editing and trying to find stuff. 'Just works' is not how I or anyone I worked with would describe it.
>all the things that they can't do because of Markdown's limitations
what are these things you're so desperate to do in Code Documentation that you can't do in markdown?
> how much harder it is to do drop-dead simple things like adding tables.
This has been a solved problem for a while now. One of the very first Obsidian plugins was the advanced tables plugin which makes it super easy to make and edit tables. There's also other apps like Table Flip. I'm sure there's probably plugins for other editors like VS Code or Table functionality built in to other markdown editors.
The only reasonable point you've got is about git. Like I said in the original post, a WYSIWYG web interface for non-technical folks which just auto commits would be preferable whilst still allowing regular git and markdown for technical folks. There's also nothing stopping anyone from doing an intermediate page if conflicts are detected with a three way conflict resolution page a la Jetbrains Editors with a magic wand auto solve. Maybe the WYSIWYG editor could automatically update if changes are detected a la Google Docs. There are lots of potential ways of solving the 'git hard' issue. There is also the built in Obsidian Sync and Publish which use git behind the scenes and give you access to full version history although I don't know if they scale well or not.
At the end of day, conflicts in documentation are less of an issue when they do happen because they're not going to cause an entire crash of a program, you're just going to have some text that doesn't make sense. In the very worse case scenario non technical people could just copy and paste things back into place from git history. Other than time wasted, it's not the same disaster as if a code conflict is not resolved properly.
Clearly they don't. You already said that you tried to pitch your solution, and you weren't able to prove its value. Atlassian is seen as reliable, and those fears are just not worth the hassle of managing your own infrastructure.
> what are these things you're so desperate to do in Code Documentation that you can't do in markdown?
1. We're talking about using Obsidian to replace a company's entire knowledge base, not just code. Code documentation is managed by technical people.
2. What are these things that are so difficult to do in Confluence that are easier in Markdown? It's a superset!
This is where you lost me and probably many who are following your comments. I have never heard anyone express what you just did about Confluence.
I don't know what accounts for the difference between our experiences, but I work with many nontechnical people, and they have a much different opinion than those who you are listening to. I certainly have never heard anyone say that everything Just Works.
Your claim that I was responding to is that "everything Just Works" in Confluence, not that Markdown is easier. I have commented on neither Markdown nor their relative ease.
> The typical gripes are around search and organization, not editing.
That would seem to contradict both that everything Just Works and that you have never heard nenontechnical people complain about it.
Unfortunately, you've inserted yourself into a conversation where this is what we're talking about. If you want to talk about something else, maybe start your own thread.
The point of contention here is that Atlassian's wiki is far easier for nontechnical people to deal with than pure markdown and git. And yes, from their perspective, it Just Works. They never wrangle with syntax, there's a massive plugin ecosystem for custom features, and version history works out of the box.
You have lost your own plot then. This is not about Markdown:
> I have never heard nontechnical people complain about the Confluence wiki. From their perspective, everything Just Works.
Except that like all WYSIWYG editors, Confluence's editor is buggy and unpredictable. You can only use it in a browser. Because it doesn't even have a 'raw' editing mode anymore, you can't work around the WYSIWYG editor when it's broken. Uploading or converting to it from external sources is a PITA, when it's even possible.
If you want technical documentation that developers are going to maintain, it has to be a joy to work with in their own editors.
WYSIWYG isn't actually better. It's a broken paradigm, and that's why every single attempt to move Wikipedia over to a WYSIWYG editor has failed.
Not what we're talking about here though, OP is suggesting it's reasonable to teach business analysts markdown and git for all company documentation.
These are table stakes features that everyone expects to work out of the box. If you don't give them a WSIWYG editor that does all of this for you automatically, it's DOA.
Would love to see how that conversation goes.
— The intern I just had to fire last month. She pretended because her generation was born with iPhones, that knowing advanced computer skills like Cmd+V was something that wasn’t a given at 21 years old. It blew my expectations about school - but at least school teaches them to find unexpected arguments.
I think her assessment of the situation is fair.
They can’t belong on the side of the world where we make things. She’ll forever belong in the people we’ve designed our apps for, viewing videos, playing games, instagram models, struggling to afford a flat. Maybe we’ll make her rich! Our apps will decide that.
Welcome to the world of non-technical people.
This, except for normals, sort of exists:
Craft: https://www.craft.do/solutions/businesses
Default 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-material
For eng teams already living in VS Code, it's hard to beat PKM where you already are.
The fact you need one person technical enough to resolve conflicts is already a deal breaker.
At the place I worked for 22 years ago, we had an SMB fileshare for designers/front-end devs (html templates + templating lang), which would simply commit everything to CVS at night.
At least you will have multiple revisions.
I had the same concern, internal documentation should be in a portable format... and I managed to mostly successfully get us to change to MD text files in a git repo.
I, and others, were tired of it being locked up in proprietary platforms like google docs - which ironically has terrible search capability and is horribly slow. Some of the devs already wrote documentation in markdown and plain text along side code (Also I hear talking about yourself in the 3rd person is the first sign of madness). So a git backed wiki in text files was what I wanted. But it also needed to generate commits from the front end for the less technical, and preferably needed oauth to delegate access control to some other system.
"Golumn" filled this space first I believe, but doesn't (or didn't at the time) have the commit or oauth capability. So I settled on a fork "Jingo" which does. I'm not completely wedded to Jingo, which is a nodejs app, I haven't dug too deeply into it and so my confidence in it is unknown... but this is effectively data driven design, md text files in git... the code (which is not part of the same repo) is disposable.
I set this up 3 years ago and haven't touched it at all. This has been mostly successful gaining more traction over time. People who have no clue how to use git are generating gits commits on a daily basis through the front end - others are using the repo directly. Google docs still has it's place for arbitrary word type stuff, but most internal internal reference type material now gets put into the wiki as a preference, since it's way more searchable, and orders of magnitude faster to access.
[edit]
To be clear, i'm in a small company where it's easier to change or try things like this.
I also got the same expected pushback, concern over MD being too limited compared to google docs and the solution being too technical. but if you can just convince people to trial it for long enough with an exit plan, they will usually obtain a more balanced view weighing the tangible benefits more highly and weighing the negatives or concerns less after actually experiencing it... in this case most people realise that all the bells and whistles of google docs are not critical, and the benefits of the searchability, speed and portability are huge.
Nah, that's going to be a crapshoot. You want a few people who know git and do this for a full time job and that's all they do - manage the documentation git repo.
- the default index on the sidebar doesn't handle sub-directories well (https://gitlab.com/gitlab-org/gitlab/-/issues/17673) - we use a pipeline to refresh an index page, but it's duct-tape and annoying to setup.
- can't edit only a section of a page, so if the page has a few sections, I often lose track of what exactly I wanted to change (maybe the WYSIWYG helps here, have to admit I have not used it much)
Otherwise I like that each project has its wiki, and so instead of one huge messy wiki, it's a few smaller messy wiki, easier to cleanup and have clear owners.
What's the benefit of your solution? I mean git has excellent history lookup capabilities, but that's the only benefit I see. Maybe another one is that you can update documents without leaving cli..
Second, because it is plain text, search is blisteringly fast using any number of different tools. Following on from that for a third benefit: portability. You're not tied to any one service. You can use any text editor for editing and you can use a multitude of different solutions for publishing. Version control? Use whatever you what.
Another benefit: easy linking of files using [[wikilinks]] and block inclusion. If this is done properly, you can also use the graph view to get an oversight on how your code affects other parts of the codebase at a glance.
If the two options are confluence and sharepoint I choose confluence every time. Somehow people have decided that because sharepoint can do document store and html it's a kb. and because it comes with O365 exec's love it because its "free".
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.
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.
Obsidian 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 Obsidian 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 Obsidian than you are with Confluence. And real people will actually be able to use what I've made there without learning complex tools or jumping through hoops.
Unless of course there's a good reason for maintaining your docs in markdown files, but all of them?
Available PLM/PDMs could be improved a lot yes, but you're not gonna replace them by slapping a GUI on git (I mean, you could do that but it's really just a pretty small part of the problem space).
I know git can be tricky but it cannot be that difficult to teach people from non technical departments add, commit and push and then show maybe one person from each department how to solve conflicts. Alternatively, build non technical people a web interface for editing and committing but allow the devs to just use git as standard. Or there's Obsidian's built in sync but I don't know enough about it to know if it scales well in large organisations.
What absolutely is definitely not the solution is Confluence. I have not met anyone who has a positive thing to say about it. The only reason it is being so widely used is because it satisfies whoever is in charge of the finances because it comes bundled with Bitbucket and Jira.