The learning curve was gentle and it seems to be able to do almost everything we need, though there are a few gotchas. (There are a lot of gotchas with the Word document, too, of course!)
For our Tuesday ad-hoc meeting I can do a demo of it. We can discuss all these details here or in the meeting:
- It's entirely offline browser-based (and open source), so anyone should be able to use it. Actually, the entire workspace is stored locally and can include many Markdown files organized in folders, including previous revisions and comments.
- The commenting system is quite nice, in some ways easier to use than in Word. Any comment starts a "conversation" that anyone can respond to. It works by storing the conversation as extra data embedded in a comment within the Markdown file.
- There's even a built-in diff tool, so if you look at one of the older revisions in the history and quickly see what has changed between that and the current revision.
- It can synchronize your local workspace with Google Drive, Dropbox, CouchDB, and GitHub. I could not get it to work with my GitHub, but Google Drive seemed extremely easy to use, and it depends on Google Drive permissions, so it's easy to allow anyone to view but only grant some people an edit permission. All the files sit in the drive and are pretty much standard Markdown, so that they can be downloaded, rendered into HTML/PDF/Word, published on a web site, etc.
- Converting the current spec to Markdown would be fairly easy. I simply opened the docx file in LibreOffice and copied-and-pasted into StackEdit. Much of the formatting was automatically converted to Markdown. Tables are a bit trickier, but also not hard to manage. I converted Chapters 1 to 3 with little trouble.
- Cross-reference links are a bit tricky. The best method I think is to create anchors using some kind of convention, e.g. "section-1.2.1.1". Of course if the sections are moved around the references would have to be updated. But, since these are simple text files, it wouldn't be hard to create a custom tool (in Python?) to search-and-replace. (By the way, the Word doc right now has a few orphaned references. Our Python tool could find such orphans and warn us about them.)
- Including images is on the one hand awkward, but on the other hand straightforward. You can use any image URL in Markdown, but that means we will need to serve them from somewhere. One possibility is to use our TC GitHub repos, which can be easily made to host publicly (via GitHub Pages). If we can get StakEdit to work with GitHub then it would be especially easy.