Documentation Analysis/Initial Proposal
Presented in Markdown format.
Title: Potential Documentation Plan for SQRL Protocol Author: Aaron Dalton Web: <https://www.perlkonig.com/about> Date: 2017-06-29T21:08:00-06 This document offers suggestions as to how to best organize and draft the documentation for the SQRL protocol. It also makes some recommendations regarding long-term communications planning and methodology. # Audience & Purpose As a professional editor, I am a vocal proponent of ["plain language"](http://www.plainlanguage.gov/whatisPL/index.cfm), which is communication your audience can understand *the first time* they read it. So before you do any work, you need to identify who those audiences are and what they need from you. ## Curious This includes journalists and people who just quickly want to understand what SQRL is all about. They are not necessarily technical experts, nor are they particularly motivated to adopt SQRL themselves. They want the most pertinent information as quickly as possible, and many will stop at this point. ## Investigators These are people who want to better understand how the system works. They don't necessarily want to or even can understand all the math, but they do want more concrete details than the simply curious. ## Users These are your basic users. They want to use the system, but they may or may not have read the more detailed documentation. They should be assumed to have no technical understanding of the underlying framework. They just want the system to work and to get the help they need when things go wrong. ## Developers & Reviewers These are the technical experts. They need all the math, all the diagrams, all the details. Developers need stable, unambiguous, and complete specifications. # Documents The problem right now is that the current website, though well written at the sentence level, is not in a structure that is easily digestible. Let's look at each of the audiences see how their needs are being met: - Curious: The landing page of the current site is 9 printed pages long and contains jargon most nontechnical folks will not understand. They will simply bounce off this page. - Investigators: Examples and case studies are spread across the 20 different webpages. And they're usually sandwiched between highly technical material they may not understand. This again causes people to bounce. - Users: There is no clear place for potential adopters to go. The word "download" doesn't even appear on the landing page. In the index the word "Client" appears twice, but in neither place is there a link for downloading an actual client. The "Projects and Finished Applications" page also lacks a link to the official reference client. And the demo page does not appear in the 20-page index. You can only get to it through the site-wide search. - Developers & Reviewers: The specification is spread out across the 20 pages, and they have to read a lot of "marketing" style writing to get to the important stuff. Given the diversity of the audiences for this system, there is no way to have a single document that will adequately serve them all. Each audience is going to need something tailored to it. ## Key Messages This is for the curious. This is your executive summary or précis. This is a single page (two pages max) that hits all the high points. It explains the key selling points of the system without getting bogged down with jargon and math. Your main website landing pages and press releases are drawn from this document. ## Case Studies These are for the investigators. These go into more detail. They demonstrate the various features of the system using concrete, easy-to-follow narrative examples. They should still avoid the technical details (e.g., names of algorithms, formulas, complex diagrams)! Only the developers need that sort of information. There should probably be at least two sets of these documents: one from the user perspective and the other from the server perspective. ## Where to Start This is for the user. You will need a page that explains how to get started. You will need links to implementations and some general initial instructions. You will also want to link to resources for how to get help and get more information. This is separate from the case studies ## Specifications These are for the developers & reviewers. These need to contain all the details. Jargon, math, and diagrams are encouraged. But they should *not* bother with the "marketing" type language used in the key messages and case studies. They should contain everything needed to implement and validate the system, but no more. They need to be complete and unambiguous. Eventually these could be prepared for submission to the IETF as a formal RFC. # Process This section only deals with the process of drafting and maintaining these documents. A discussion of how to actually present them to the world comes later. The ideal process accomplishes a few things: - Makes the material as visible to as many potential collaborators in the most frictionless way possible. - Allows some degree of access control. - Makes it easy for people to make concrete contributions to the text. - Also involves some sort of issue tracker for people uncomfortable making concrete contributions where they can express more abstract concerns that others can help correct. - Includes version control and tracking. As far as single service providers go, [GitHub](https://github.com) seems ideal. - Steve can create and own the SQRL organization, into which he can bring contributors (and repositories) as he sees fit. He has control over the master versions. - Pull requests make it possible for people to make concrete suggestions that (if unobjectionable) can be quickly and easily merged with minimal work for the maintainers. - The built-in issues tracker makes it possible for people uncomfortable with Git to make suggestions and express concerns that other contributors can act on. - The site makes it easy to directly edit files so you don't have to download and learn how to use Git if you don't want to. - It has hosting features like GitHub Pages and integrates with many, many other cloud services. If we went with Git, then I recommend using [the GitFlow branching model](http://nvie.com/posts/a-successful-git-branching-model/). Not all of it's features apply to document repositories, but it's a good way to keep disciplined. Since the IETF publication process uses [Markdown](http://commonmark.org/) and it's simpler than formats like [reStructured Text](http://www.sphinx-doc.org/), I propose using Markdown throughout the drafting process. # Long-Term Communications Planning I don't know what Steve's long-term plans are; these are just my musings. Once these documents are stable, you can decide what to do with all that material. Below are some of the questions I would start asking: - What URLs have already been registered for this project? - What do you see being your canonical URL? - Do you envision all these documents living under <https://www.grc.com> or are you open to an independently designed site? - What are your plans for user engagement? While NNTP has lots of benefits, it's a dead protocol. I couldn't find a single browser client that would let me meaningfully interact with your private server. I had to download a dedicated client. The vast majority of people (especially the curious and the investigators) will never, ever consider doing that. - Are you open to preparing the spec for submission as an RFC to the IETF or other standards body? Have you done that sort of thing before? - What's your plan for reaching out to large industry players and how do you see these documents fitting into that plan chronologically? - How many people are actively participating now or are prepared to actively participate in this drafting process? - What skills exist in the pool of current and likely participants (e.g., web designers, graphic designers, technical writers, etc.). - Is there a budget for filling in skill gaps or an appetite to raise funds if necessary? I should clarify that these are rhetorical questions. Nobody is beholden to me. These are just the sorts of questions I ask authors in my day job. # Next Steps There are a few decisions that have to be made before doing anything: 1) Is this approach to drafting separate, focused documents acceptable? 2) If so, what process should we use to manage the files (e.g., GitHub)? 3) Who will do whatever initial setup is required for the chosen process? After these decisions are made, the biggest first step is doing an initial rough draft. I am happy to do that, but I don't want to waste time unless there's some consensus on the premise and process. My approach would be as follows: 1) Go through each and every line of text on the <https://www.grc.com/sqrl> pages and copy the text into the documents that seem most appropriate. 2) Then go through each of those documents, cull duplicate material, and do an initial outline based on the existing material and any identified gaps. 3) Once that's done, people can start to review and collaborate on finalizing the material. 4) Once the documents are stable, then we can look at designing a website that presents this information in a way that is accessible to the various audiences in an engaging way.