Re: [Emo-dir] quick-start guides

[Jay Daley <[e-mail]>]

When I looked at quick start guides before the new year there were some unanswered questions getting in the way.

1. As below, do we recommend Markdown over XML or let people choose?  The authors site currently lets people choose but that can change.

2. Do we recommend kramdown-rfc over mmark or let people choose?  kramdown-rfc is used much more than mmark so that would be fair but it’s still odd that we should pick a winner.

3.  Do we recommend going straight in with Martin Thompson’s templates?  The recommendation from Ekr on another list was "I would think one with XML and one with Markdown and a separate one for how to use MT's ID tools, which means Github."

If we’re going to include all of those then that’s four quickstarts and they still need to choose between them.  Doable but not as snappy as perhaps we might hope.

Any thoughts?

Jay

> On 31/01/2022, at 9:45 PM, Lars Eggert <[e-mail]> wrote:
> 
> Signed PGP part
> Hi,
> 
> do we want to (strongly) recommend kramdown-rfc2629 esp. for new documents?
> 
> It has a significantly lower bar than editing directly in XML.
> 
> Thanks,
> Lars
> 
> 
>> On 2022-1-27, at 20:11, Alice Russo <[e-mail]> wrote:
>> 
>> As discussed today. Outlines below as potential starting points.
>> 
>> Alice
>> --
>> 
>> A) Quick-start guide for editing in XML
>>  - Start with a file (an existing I-D or template [1]).
>>  - Edit it w/ the software of your choice.
>>    -> Tip: Rely on the citation library by using xi:include [2].
>>  - Convert it using https://author-tools.ietf.org.
>>  - Upload it to the I-D submission tool [3].
>>  - Share it and update it.
>> 
>> B) Quick-start guide for editing in markdown (specifically kramdown-rfc2629)
>>  - Start with a file (an existing I-D or template [4]).
>>  - Edit it w/ the software of your choice.
>>    -> Tip: Rely on the citation library by using a YAML header [5].
>>  - Convert it using https://author-tools.ietf.org.
>>  - Upload it to the I-D submission tool [3].
>>  - Share it and update it.
>> 
>> Note: If you prefer a GitHub workflow, see instructions on [6].
>> 
>> [1] https://github.com/ietf-authors/rfcxml-templates-and-schemas/blob/main/draft-rfcxml-general-template-standard-00.xml
>> [2] https://authors.ietf.org/references-in-rfcxml
>> [3] https://datatracker.ietf.org/submit/
>> [4] https://github.com/martinthomson/internet-draft-template/blob/main/draft-todo-yourname-protocol.md
>> [5] https://github.com/cabo/kramdown-rfc2629#references
>> [6] https://github.com/martinthomson/i-d-template/blob/main/doc/TEMPLATE.md
>> _______________________________________________
>> Emo-dir mailing list
>> [e-mail]
>> https://www.ietf.org/mailman/listinfo/emo-dir
> 
> 

--
Jay Daley
IETF Executive Director
[e-mail]