Technical Documentation and Training System Utilizing Markdown and Live Updates

Question

This may not be the correct place to post this question, but I'm at a loss of where else it can go.

I'm attempting to research a potential documentation system for my company to use that would replace our current system for storing, publishing, versioning and sharing our training and technical documentation. However, I cannot seem to find any existing system that would match all of our needs.

Here's the current list of features I am currently trying to look to solve:

• Uses Markdown for the actual document
• Markdown files are contained in a VCS (version control system) or some other system for file versioning and acceptance
• As soon as the files are updated (through the versioning system) the changes become live to wherever it is posted
• The outward-facing document library is user friendly and simple (much like a wiki or help document library like Adobe's)
• Only certain people (for example, our organization) can view the published document library
• The published documentation could be printed or exported to PDF for users

I saw that Adobe keeps their educational documents in a Git repository, which means they can write in Markdown and have access to a VCS, but they don't state what it looks like to get those documents published to their knowledge center.

So far the idea of perhaps hosting a Git Page could work, but the issue of keeping it private to the company still remains. I'm also looking for a way to keep the amount of potential overhead down if possible, as the people I work with are not familiar with things like Git or VCSs.

The ideal would be to somehow utilize SharePoint, as our company heavily uses it as it is, however I cannot seem to find an appropriate way to utilize SharePoint's version system, make the files in Markdown, which then post the changes live to an outward-facing document library.

Anyone have solutions that could potentially match these needs? I will gladly look at other resources or alternatives to anything I've listed here as "features".

Answer 1

GitBook checks all your boxes. It uses Markdown. It uses versioning with Git. On its upper tier plans, it supports PDF exports. It supports both internal/private and public-facing docs.

https://www.gitbook.com/

Answer 2

I'd say any wiki will do this, but MediaWiki (Wikipedia's system) and DokuWiki are the ones I know.

The basic logic behind most Wikis was originally that they expose the system to "whomever" and use versioning to protect against inappropriate edits.

Pretty soon it became apparent that there needed to be more than that so both DokuWiki and MediaWiki have access management to give read, write or no access (i.e. pages you can see but not edit, or can see and edit, or can't see).

Since both can be installed locally, you can put them behind whatever firewalls and other protections you like. I'm also pretty sure they both have integration with AD/LDAP to allow single sign on etc. But I haven't tested that.

But there are many more plugins for both wikis that will be able to do pretty much anything both better and worse (in my opinion). MediaWiki has LUA support (programmable templates) and DokuWiki has the ability to parse PHP directly (very NOT recommended unless all users are unwilling to hack the server etc... but it's also programmability... kind of...)

I've tried both but opted to go with DokuWiki for two main reasons. It's only me (no need for a hunking database) and it saves the pages as markdown text files in the file system so even if the software goes totally kaput, I have the files in pretty much readable format on the disk.