Grav was put forward by the MIRACL team because of several reasons. First, writing in JSON for any kind of technical documentation is not a low barrier to entry. Markdown is the proper way to do this to democratise the process. Actually Markdown and Latex, which is converted via MathJax dto nice cryptographic notation, which Grav supports. Keep in mind that a lot of the lower level docs and functionality needs to be written not by folks who understand JSON but are academic cryptographers who have already written their information in Latex. In our experience, doing this conversion via a static website generator such as Jekyll has produced spotty results.
Second, again, Grav IS A FLAT REPO. It's flat file CMS. It's requirements are just a web server with PHP and two mod modules. You can see the requirements here: http://learn.getgrav.org/basics/requirements This isn't like we have asked to host Wordpress or some bloated monstrosity (sorry Wordpress lovers). Third, because it is flat we can do versioning control on the Markdown docs via Git or other version control system just as Jamal has suggested. That IS our intention. Whether that fits within the Apache Way or not, I'm not sure, but we want to make sure that the text information on the website can managed via a common developer utilised version control system, and Git would be our preference (actually GitHub). So clone the repo, make changes, make a pull request, etc. to merge your changes on the Markdown docs, which are the foundation of the website. So this ins't for just the technical docs, this is for the entire Milagro web site. Fourth, Grav has an extensive set of plugins and tooling that can enable a richer experience above and beyond just a flat file CMS site. Without going into laborious detail, we would like to have a discussion forum, automated form to auto-enrol folks into the Milagro Slack (our not having this has come up more than once already) and the ability to showcase some of the technologies that Milagro Project (incubating) has that are relevant to web apps and mobile authentication. Namely, these are Milagro MFA (multi-factor authentication) using the M-Pin Protocol. In short, we would like to be able to show this in the Milagro site. Here's the Pin Pad version, here is the headless version, etc. Makes sense, right? While this certainly can be done in pure JavaScript, PHP is still the dominant language found on most production web sites, even today. Being able to inspect that code in the repo and have it demonstrable in the Milagro site itself makes the technology "real" in our view. @Nick Kew, hopefully this makes sense to you to carry the request to the infrastructure team? Not sure how we thought we were going to get their attention on the dev milagro list in the first place but smarter folks than me hopefully have worked this out. How do we get an answer from the infrastructure team on this? To reiterate, the question is: Will they host Grav, which is a flat file CMS, for the Milagro site? The requirements are listed here: http://learn.getgrav.org/basics/requirements On Wed, Apr 6, 2016 at 5:44 PM, Jamal Natour <[email protected]> wrote: > > > Is that a matter of familiarity and/or legacy? > > > Are there existing docs managed by grav that want importing? > AFAIK there are no legacy requirements, and we want to be as open and > transparent a community as possible. > I'd really like this to be here is everything in a flat repo, so any > external contributors are as empowered to make changes as a Miracl staff > member. > We already do public development, with pull requests as our internal > workflow, and I think that us publishing JSON for content and HTML for > layout from a public git repo is a fairly low bar to entry. > > I'm a little uncomfortable with us *needing* more than that for > documentation, as it suggest some business process is being delegated to > tooling. > If we have business needs to accommodate, we should split this off into a > possibly internal discussion on how *PE* and *DEVOPS* can best support > these needs. > > Otherwise, I'd prefer that docs are stored alongside code in git, and are > handled like code. > I'd would like to avoid any "in-house only" magic to produce docs > especially where we must engage with people who cannot use such visual > tools due to visual impairment or other accessibility needs. > > Using a "Git first" workflow will allow us to support email, web, users of > assistive technologies, as well as a range of desktop and mobile clients. > > > > > > > On Wed, Apr 6, 2016 at 1:38 PM, Nick Kew <[email protected]> wrote: > > > On Wed, 6 Apr 2016 14:36:49 +0300 > > Vladislav Mitov <[email protected]> wrote: > > > > > I agree with Jamal. We can build it with some kind of static site > > > generator for convenience, but we don't need this thing on the server > > > for sure. > > > > Indeed. Existing apache projects use a range of publishing > > models and templates. We could certainly ping infra about > > using the Apache CMS if some folks would prefer, but I think > > they'd want a pretty compelling case to support a whole new > > system. > > > > The most likely trigger to adopt it would be demand coming > > from a range of projects. As in, when git was introduced, > > or arguably even when svn replaced cvs! > > > > > > > That is why it is extremely important to have it clear, > > > > > understandable, and even more important - easy to access and edit > > > > > if needed. > > > > That is a problem to which many solutions are available. > > > > > > > > > > > > Having that in mind I want to raise a discussion here about using > > > > > a GRAV https://getgrav.org > > > > > This is flat file CMS, with no backend database to support. > > > > Is that a matter of familiarity and/or legacy? > > Are there existing docs managed by grav that want importing? > > > > Bear in mind that unless there's a pretty substantial legacy > > to deal with, committers can be expected to come from a range > > of different backgrounds and adapt to whatever tools are used > > for a particular project. > > > > -- > > Nick Kew > > > -- Brian Spector CEO MIRACL T: +44 (0) 20 3389 8190 https://www.miracl.com 81 Rivington Street London UK, EC2A 3AY Registered in England and Wales 7017635
