[Tools-arch] First-time contributions

[Martin Thomson <[e-mail]>]

On Thu, Sep 3, 2020, at 01:51, Silvia Botros wrote:
> should we consider in this conversation existing IDEs/editors people 
> may use to create these artifacts? it seems to me that Markdown editors 
> are far more on the rise than XML and that would be part of the 
> equation for someone about to start a document. 

I think that is part of it for sure.  I think that balancing angle brackets tends to lead to XML-based editing being cumbersome.  But that makes me think more about the overall flow.

The main thing I concern myself with is the cycle of operations required for the first contribution.

If someone is familiar with email, you read a draft, find a nit, copy the relevant paragraph and section number, open a mail client, paste them in, add some comments, find the right email address, join the mailing list, send the email.

If someone is familiar with the github flow, you read a draft, find a nit, find the repository, fork the repository, clone the repository, setup remotes, make a branch, edit the document, make a commit with comments, push to your fork, open a pull request.  Maybe you also open issue instead, which is slightly easier (this is more common).

These are both high-friction processes.  So those who contribute are usually fairly well invested [1].  Right now, the only things we do to help are ad-hoc.  We sometimes put text near the front of a document that explains how to find the mailing list or repository.  We can almost certainly do better.

[1] The number of drive-by contributions on GitHub is non-trivial, which is - I believe - a positive artifact of the culture that has arisen there.