I've been trying to figure out the best way to make supporting documentation available. During the development phase of our projects the documentation is in flux a lot, so it needs to be something easy and flexible.
My latest attempt was to use Github Wikis:
https://github.com/jiscdev/learning-analytics/wiki
That gives us nice clear documentation, and is really easy to manage, track changes etc. The problem is it's not terribly friendly for non-techies.
My solution was to use the a combination of Sails.js (and overkill really!) and Showdown (https://github.com/showdownjs/showdown) to create a simple service that takes a wiki pages, formats it, and changes the URLs so that they also link to the formatted version. The end result came out pretty well:
https://docs.analytics.alpha.jisc.ac.uk/docs
The only really hacky thing I had to do was parse the incoming text for <pre> tags, and manually add <br/> at the end of each line to get code to format well. The end result of that worked pretty well too:
https://docs.analytics.alpha.jisc.ac.uk/docs/lrw/Technical-Guide:-Basic-UDD-Queries
Popular Posts
-
****Updated for XCode 5 **** Looking at the forums it seems a lot of people are having trouble getting iADs working on Cocos2d-x on iOS. ...
-
Update version here: http://www.mwebb.me.uk/2016/01/full-screen-zx-spectrum-on-raspberry-pi.html --------- I'm making a spectrump...
-
You'll find the status bar (with the battery, time etc) appear in your app in XCode 5/iOS 7 when you use Cocos2d or Cocos2d-x. To stop ...
-
I've found a fairly easy way to add Interstitial Admob to Android applications. For me, iOS is easy, as I can code in Objective C, but...
-
It's not obvious how to extract Android NDK for Mac, so I thought I'd share the solution. You have to do it from terminal. Change ...
-
I guess this is obvious if you know it, but I've only just found out. Mac OS's Preview application can open Adobe Illustrator (.ai) ...
-
Google have sent out emails to developers about the latest security hole in open SSL. The text says something like this: One or more of yo...
-
Here's my Raspberry Case. As you can see, it's housed in a Spectrum Microdrive case! Don't worry, it was a broken one. ...
-
With the default Cocos2dx template the back button on your phone won't close the application. Without this your app will fail the test ...
-
I think this one is a bug in Xcode 5, as it didn't used to happen. When I tried to validate an app it matched it to a different app (i....
No comments:
Post a Comment