Re: Things that used to be clear (was Re: Evolving Documents (nee "Living Documents") side meeting at IETF105.)

["[e-mail]" <[e-mail]>]

Sarah

See RFC 5385, J. Touch 
Version 2.0 Microsoft Word Template for Creating Internet Drafts and RFCs

I've used the Word template for writing what became an RFC. I later found XML easier to collaborate on with better group revision control, for diagramming, and better for complex documents.

Most technical documents (and code) start by editing down another document to get a framework to work in and expand...

L.

at least it's not LaTeX....

Lloyd Wood [e-mail] http://about.me/lloydwood



On Thursday, 11 July 2019, 01:02:45 GMT+10, Sarah B <[e-mail]> wrote: 


If we want to make the IETF approachable for all, then for me this statement from Stewart is true, and part of the problem. I'm not an engineer. I don't spend my days in code. Github is not part of my workflow. More over, as a newcomer, i think the idea of cribbing someone else's draft and using it as a basis is probably a non starter. I share Kathleen's musing, in that I wonder too what will be popular in <x> years from now. I'll take the unpopular stand that being able to write in (gasp) Word docs works perfectly for me - in fact, it's highly desirable. :)

</rathole>
Sarah

> On Jul 10, 2019, at 7:47 AM, Stewart Bryant <[e-mail]> wrote:
> 
> 
> If you don't like XML, use Markdown.
> 
> There is not a lot more to remember than a # to start a section level
> and four spaces for a figure.
> 
> The header template is a bit strange, but you crib that from an existing draft, then you need a few minor bits of # and {} for references and you know everything you need to know for 99% of the work.
> 
> - Stewart
> 
> On 10/07/2019 15:11, Adrian Farrel wrote:
>> Is it really that hard?
>> Even crusty old idiots like me have worked out how to use an editor to make XML that is acceptable to XML2RFC. I doubt that I am clever or more talented than Fellows of major engineering organizations.
>> All tools (even github) require to be learned.
>> Replace tools with better tools, by all means.
>> But don’t make changes for personal preference: that way lies unending debates about whose preference is best.
>> Thanks,
>> Adrian
>> *From:*ietf <[e-mail]> *On Behalf Of *Richard Barnes
>> *Sent:* 10 July 2019 14:57
>> *To:* Randy Bush <[e-mail]>
>> *Cc:* Julian Reschke <[e-mail]>; IETF Rinse Repeat <[e-mail]>
>> *Subject:* Re: Things that used to be clear (was Re: Evolving Documents (nee "Living Documents") side meeting at IETF105.)
>> I'm glad it works for you.  The non-IETF-habituated new authors I've worked with have found it mystifying.  Including everyone from junior engineers to Fellows of major engineering organizations.
>> As Christian says, our continued attachment to bespoke tools is a barrier to getting new work in the IETF, and thus detrimental to the long-term health of the organization.
>> --RLB
>> On Wed, Jul 10, 2019 at 9:47 AM Randy Bush <[e-mail] <mailto:[e-mail]>> wrote:
>>    >> Tooling is just one of the problems with XML2RFC. The real issue is
>>    >> that XML2RFC is completely specific to the IETF. This translate into
>>    >> training ...
>>    > It also has been optimized for the production of RFCs. Also note that
>>    > many changes in the v3 vocab just align the language with HTML (lists
>>    > and tables come to mind).
>>    from an xml non-lover:
>>    xml2rfc rocks!  it produces the baroqe, designed by committee, internet
>>    draft format from input which i can easily produce in my text editor.
>>    and the support, maintenance, and responsiveness of the tools team is
>>    simply stunning.
>>    [ and for the poster who wished for a gooey, there is one ]
>>    thank you!
>>    randy