[Wg-uma] RFC: Specification authoring process

Christian Scholz cs at comlounge.net
Tue Aug 25 03:25:46 PDT 2009


Iain Henderson wrote:
> I'm not that technical - so the longer we stay in Confluence/ wiki mode
> the better from my perspective.

I think we probably have some phases in which we flesh out
specifications. We might start with some brainstorming,
strawman-proposals etc. and refine them a bit until the general concepts
are clear to us. This includes of course use cases and so on.

Then I'd move it to svn and xml2rfc for putting all the details and
formalities in there.

I assume that we still can add comments to the exported HTML on the
wiki? If so that would be good for capturing feedback. Eventually we
might also want an issue tracker like trac or so (not sure if kantara
has something already installed).

Once the spec gets more formal I think it's a good idea though to also
use a proper tool for managing it like xml2rfc and subversion.

I am not sure how this fits with the proposed agile method though. It
might depend how soon we go into formal mode. Once we have to rewrite
everything because of our agility we might want to start over completely
and eventually copy parts over which are still valid.

I hope though that we can reduce that work by having a modular spec so
that only parts need to be rewritten and exchanged.

-- Christian

> Cheers
> Iain
> On 24 Aug 2009, at 23:43, Eve Maler wrote:
>> This approach seems sound to me.  It meets my goals of:
>> - Authoring in a format that multiple people can contribute to
>> - Targeting IETF in deed as well as in word
>> - Producing native HTML in an attractive format that will hopefully
>> appeal to developers
>> - At least middling levels of content management, such that diff
>> redlines can be viewed
>> I think we're still fine with native Confluence as the source form for
>> auxiliary non-normative documents.  (Note that xml2rfc wouldn't be
>> suitable for any document that relies on graphics, as it doesn't allow
>> non-ASCII graphics per IETF.)
>> Thanks for looking into it, Paul!
>>     Eve
>> On 24 Aug 2009, at 3:16 PM, Paul C. Bryan wrote:
>>> During our discussion in last week's conference call, we began
>>> addressing how the specification should be authored, where content is
>>> hosted, etc.
>>> I was leaning towards using a tool like xml2rfc [1], as it provides
>>> IETF-compliant output in a number of useful formats.
>>> Before proposing an approach, I first wanted to determine how Kantata
>>> would be hosting files. After contacting staff, I have learned that they
>>> allow revision control of files via Subversion and allow publication of
>>> raw HTML on the wiki.
>>> This seems to be a good fit for me to propose the following approach:
>>> 1. The protocol specification will be authored in the xml2rfc schema.
>>> 2. The master source file(s) for the protocol specification will be kept
>>> in Subversion.
>>> 3. When changes are made, xml2rfc will be run to generate HTML content.
>>> 4. HTML content will be published through the wiki as raw HTML.
>>> 5. Formal versions of the spec will be tagged in the Subversion
>>> repository.
>>> 6. HTML output of the formal versions be retained separately in the
>>> wiki.
>>> Please let me know if you have any questions or objections to this
>>> proposed approach.
>>> Paul
>>> [1] http://xml.resource.org/
>>> _______________________________________________
>>> Wg-uma mailing list
>>> Wg-uma at kantarainitiative.org
>>> http://kantarainitiative.org/mailman/listinfo/wg-uma_kantarainitiative.org
>> Eve Maler
>> eve at xmlgrrl.com
>> http://www.xmlgrrl.com/blog
>> _______________________________________________
>> Wg-uma mailing list
>> Wg-uma at kantarainitiative.org
>> http://kantarainitiative.org/mailman/listinfo/wg-uma_kantarainitiative.org
> Iain Henderson
> iain.henderson at mydex.org
> This email and any attachment contains information which is private and
> confidential and is intended for the addressee only. If you are not an
> addressee, you are not authorised to read, copy or use the e-mail or any
> attachment. If you have received this e-mail in error, please notify the
> sender by return e-mail and then destroy it.
> _______________________________________________
> Wg-uma mailing list
> Wg-uma at kantarainitiative.org
> http://kantarainitiative.org/mailman/listinfo/wg-uma_kantarainitiative.org

Christian Scholz                          Homepage: http://comlounge.net
COM.lounge GmbH                              blog: http://mrtopf.de/blog
Hanbrucher Str. 33                                       Skype: HerrTopf
52064 Aachen                             Video Blog: http://comlounge.tv
Tel: +49 241 400 730 0                           E-Mail cs at comlounge.net
Fax: +49 241 979 00 850                               IRC: MrTopf, Tao_T

neuer Podcast: Der OpenWeb-Podcast (http://openwebpodcast.de)
new podcast: Data Without Borders (http://datawithoutborders.net)

More information about the Wg-uma mailing list