Design docs / Markdown / doc restructuring

Mike Hearn

Doc restructuring. I’ve restructured the left hand navbar to be split into four sections:


  • Development
  • Operations
  • Design docs
  • Participate


I haven’t done a deep re-org of the current content, but the idea is that now we have a stronger division of sections it’ll encourage improvements to our operational documentation.


Design docs. The design documentation for open source features are currently in the tech white paper, or in various miscellaneous wiki pages and discourse posts that need to be gathered together. This is messy. The tech white paper is a useful one-stop-shop to learn about the platform design at a high level, and it’ll stick around for that purpose (updating it is on my todo list). But we have a lot of features that are incidental, or are of a level of detail that wouldn’t help readers of the tech wp. So this new section is useful for these, along with things like alternatives considered.


The design docs I just moved into the docsite are, for now, features that only appear in our Enterprise edition (not released yet, but we’re hard at work on finishing the first version). There’s no particular reason for this – it’s just that we happened to start using git and markdown to gather design docs instead of wiki pages around the same time we started work on enterprise features. As we gather info  from other places it’ll become a mix of design docs for open and proprietary features, so it’s an ongoing project.


This approach is pretty unconventional – why are we exposing detailed design thinking for a commercial product alongside the docs for its open source version? We went back and forth on this and eventually concluded it was better to be as open as possible. The major key ideas of Corda are all given away for free anyway, so the difference between our enterprise edition and the open source version is primarily in better execution rather than ‘secret sauce’. As our users are mostly working in industry, and tend to have very detailed opinions about infrastructure design, it makes sense to just work closely with people on enterprise features too. That way we’re less likely to have requirements mismatches when people want to deploy. Also sometimes features may migrate from enterprise to open and then we’d need to publish the design docs anyway.


Markdown. The design docs are written in Markdown not ReStructured Text, for historical reasons (the previous state didn’t have them be published in any part of the website beyond github). As part of this work I’ve activated support for Markdown in the docsite. Markdown files in the docs build can embed RST directives like “.. note::” or “.. toctree::” – however, please be aware:


  • We should probably restrict Markdown to the design docs section. Let’s keep using RST for the rest of the site.
  • Sphinx converts Markdown to RST at build time automatically, this is why you can mix and match in a flexible way but has the disadvantage that line numbers in error messages are all wrong. To debug, enter the virtualenv and run “m2r path/to/my/” – the rst file will be put in the same directory and you can then examine the conversion.
  • Because it’s being converted to RST on the fly, Sphinx is pickier about markup correctness than a normal Markdown parser is. It will still whinge if you unbalance your nesting levels, if you unbalance your asterisks etc. This is one reason why it’s probably not worth trying to convert the whole site or anything, even though Markdown is in some ways a more convenient syntax.

Join to automatically receive all group messages.