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.
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:
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:
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.