Documentation Analysis/Initial Proposal

From SQRLauth.net
Jump to: navigation, search

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.