The Problem

I have been searching for a way to collaborate on documentation for software projects for a long time. While the projects to be pretty complex, our needs for bells and whlstles is low. Our requirements are:

• Minimal intrusions from notifications
• Markdown centric
• Granular access controls
• A reasonable pricing structure. That’s really it. We tried several documentation systems, and they were all either overkill, or created documentation that smacked of psychopathy.

The current solution

Putting together some of our everyday freebie tools seems be creating a viable solution. We’ve been using the following:

• Obsidian - A free markup document management solution.
• SharePoint - Microsoft’s OneDrive based file sharing system.

Obsidian allows users to create a “Vault” of files, or, more effectively, manage an existing directory of Markdown files.

SharePoint allows users to share a directory among collaborators. The directory owner can assign access privileges to collaborators on a folder-by-folder basis.

This all sounds great until.

One small hitch

The issue with this solution is that each Obsidian user connecting to the documentation folder expects a .obsidian directory in the root of the vault. The problem is that most users have highly customized Obsidian installations. Forcing the users to share configurations is not a practical solution.

The Fix

The fix to this problem is to create a symbolic link in the SharePoint drive that points back to the user’s local drive. Please note that the user must complete this step before accessing the directory with Obsidian for the first time.

When setting this up for the first time, you’ll need to create a destination for your obsidian configs:

mkdir -p ~/.obsidian-configs/<vault-name>

Then, in SharePoint, create a link to the .obsidian directory:

ln -s ~/.obsidian-configs/<vault-name> /path/to/your/vault/.obsidian

Also keep in mind that each user must do the above step before accessing the directory with Obsidian. Once they do that, the Obsidian configurations will be referenced from their local drive.

Not a super big hitch, but there’s always a hitch.