Doc restructuring. I’ve restructured the left hand navbar to be split into four sections:
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: