DocuBricks format: MarkDown vs XML

[rwb27]

As a result of a few discussions I've had, I am interested in finding a more human-readable representation for DocuBricks format documentation. The obvious candidate for this seems to me to be MarkDown. My aim is to fix a few issues that have held me up from documenting various projects in DocuBricks:

• The XML files are not particularly human-friendly, particularly because they are long and make heavy use of unique identifiers that are long strings of numbers and letters, with no obvious meaning.
• The Java-based editor/viewer does not yet support the formatting features I added to the HTML viewer last year
• Viewing the files requires either the Java editor, uploading to DocuBricks, or setting up the modified HTML viewer - none of these provide an instant preview
• Despite our best efforts, DocuBricks is not yet a well-known standard, and so people assume it is not editable when they see it in my Github repository. This is possibly the biggest issue for me - it makes people feel the project is less open, despite the fact that it's specifically designed as an open standard!

I am interested in using MarkDown to represent the same information you get in a docubricks XML file. I think this has a number of advantages:

• MarkDown is very human-readable, and is familiar to most people (e.g. via Wikipedia, Github, etc.)
• There are already a variety of mature, stable, high performance editors and renderers for MarkDown, many of which work very nicely in a browser.
• MarkDown would lend itself to a one-file-per-brick representation, which would be easier to navigate in a text editor
• Support for basic (safe) formatting and hyperlinks is built in
• Previews and rendering are easily introduced via projects like Jekyll, and would almost certainly play nicely with something like Electron if we wanted an offline WYSIWYG editor.
• MarkDown is a very well known standard, and with the addition of a little extra metadata (perhaps in YAML format) would be convertible to docubricks XML in either direction.

A few of us are likely to have a hack session to see if we can make this work at some point in the next few weeks/months, and I'll report back here if it looks promising.

[MakerTobey]

This is now the upcoming development focus.