Re: [Emo-dir] quick-start guides

[Andrew Campling <[e-mail]>]

On 2 Feb 2022, at 14:32, Karen O'Donoghue [e-mail]<mailto:[e-mail]> wrote:

> I strongly agree with Mirja here. The problem we were discussing last week was how to help people get started... quickly... without overwhelming them with options and choices. I think we need a very limited set of choices in this instance. At the end of the short quick start guides... we can point to more information and detailed instructions elsewhere.
>
> Remember this can always evolve as we learn more. Done is better than perfect.


I agree that the emphasis should be on simplicity, although I can see the temptation to offer multiple options given there are different types of new authors that may benefit from this guidance.  To simplify things, it may be useful to have something like:

"Software developers familiar with GitHub should start here ... (a single path with as few steps as possible to get to draft submission)

Technical authors with experience of markdown should start here ...

Technical authors familiar with XML should start here ... "

Etc

No doubt agreement on appropriate labels for the various categories will need discussion, the idea would be to point to a single path for each one from start to finish, potentially signposting additional material at the end such as more sophisticated templates and tools for those that aspire to more advanced documents.  NB I think that we should be cautious with paths that are dependent on tools being loaded onto devices as this may present a problem for some enterprise policies, although this should be fine as part of a list of additional material and tools.

We are still missing something suited to less sophisticated potential authors that may nevertheless be able to offer valuable contributions including, for example, those from civil society, industry bodies and other groups of end-users not versed in the use of GitHub, Markdown etc.  The current options are still likely to be perceived as a significant barrier to entry for some compared to, for example, a step-by-step guide to producing an I-D using Word.  Others may disagree but I firmly believe it is important to make it possible for such groups to participate if the IETF is to diversify the membership beyond the tech and telecoms sectors.


Andrew