Re: [Emo-dir] quick-start guides

On Tue, Feb 01, 2022 at 04:44:13PM +1300, Jay Daley wrote:
> 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.

Afaik, XML was never designed for direkt human writing. Mardown is.
Arguably this means that we should have and recommend a markdown
language for writing.

As i said in my prior mail, if we recommend then this puts us in a bit
of a bind to document/tool-support the markdown as much as the XML (IMHO).
Aka: additional work for tools team (although i think it's not much work).

> 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.

I would just put "recommend" into context. It just means that the recommended
choice is the one where tools team will spend resources on and where it
seems more members of the community can provide peer-2-peer support.

> 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."

Repeating: I would like to see a template that has an instance of all
important formatting options and all useful sections, and have it the
same for XML as for markdown. The XML template is already quite good,
the markdown one weak.

No opinions about the importance of the github piece.

> 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.

I'd start with kramdown-rfc markdown and XML quickstarts.

Toerless

> Any thoughts?
> 
> Jay
> 
> > On 31/01/2022, at 9:45 PM, Lars Eggert <lars@eggert.org> 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 <arusso@amsl.com> 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
> >> Emo-dir@ietf.org
> >> https://www.ietf.org/mailman/listinfo/emo-dir
> > 
> > 
> 
> --
> Jay Daley
> IETF Executive Director
> exec-director@ietf.org
> 

> _______________________________________________
> Emo-dir mailing list
> Emo-dir@ietf.org
> https://www.ietf.org/mailman/listinfo/emo-dir

-- 
---
tte@cs.fau.de