[KI-LC] Another doc authoring tool question

Andrew Hughes andrewhughes3000 at gmail.com
Wed Sep 14 12:56:27 CDT 2016


I'll leave it to the IETF I-D and RFC contributors and editors to reply :-)

You are correct that there are more than one distinct
contribution/collaborations times.

The third phase in the mix is group maintenance post-publication. Initial
publication is not too bad with the disconnected tool chain.

I think we might be missing a) a spec for those intermediary formats, b)
the list of recommended tools, c) current output templates, d) a flow
description of how to go from point to point in the publishing chain, e)
advice on how to use versioning techniques like github or Word to
accurately capture group/public input.

(Eve and others started down the path of gathering the info and so on, but
LC didn't pick up and complete the task)

andrew.


*Andrew Hughes *CISM CISSP
Independent Consultant
*In Turn Information Management Consulting*

o  +1 650.209.7542
m +1 250.888.9474
1249 Palmer Road,
Victoria, BC V8P 2H8
AndrewHughes3000 at gmail.com
ca.linkedin.com/pub/andrew-hughes/a/58/682/
*Identity Management | IT Governance | Information Security *

On Wed, Sep 14, 2016 at 10:44 AM, John Wunderlich <john at wunderlich.ca>
wrote:

> There seems to be two issues - enabling a broad base of content creators
> to create content and the need for a tool up to the task of creating and
> maintaining complicated documents. Why not split the problem?
>
> Leave content creation tools up to the writers and SME's in each WG, but
> specify what are acceptable output formats for content (plain text,
> markdown, and Word for example) as input to final document editors.
>
> Then give the final document editors the King Kong tool they need for
> complex documents. This could be limited to WG editors and Kantara staff to
> keep costs down and support down.
>
>
>
> Sincerely,
> John Wunderlich
> @PrivacyCDN <https://twitter.com/PrivacyCDN>
>
> Call: +1 (647) 669-4749
> eMail: john at wunderlich.ca
>
> On 14 September 2016 at 13:27, Rainer Hoerbe <rainer at hoerbe.at> wrote:
>
>> WG-FI is using Asciidoc for the Fedinterop Profile
>> <https://github.com/KantaraInitiative/SAMLprofiles/>. The layout is
>> pretty close to the Word template for Kantara reports.
>>
>> Asciidoc is good enough for technical documentation of medium complexity,
>> much more powerful than Markdown, but again with a learning curve. We are
>> using a simple Github/Asciidoctor/github.io tool chain to edit,
>> versionate, generate and publish pdf and html. There is a docbook backand
>> as well, but we found no need so far to try this.
>>
>> - Rainer
>>
>>
>> Am 14.09.2016 um 18:58 schrieb Andrew Hughes <andrewhughes3000 at gmail.com
>> >:
>>
>> This is exactly the core of the question I'm trying to explore...
>>
>> I'm trying to find some kind of balance between powerful-but-nasty
>> formats and tools and the capabilities for community contribution.
>>
>> Kantara has a problem that we are using word processing tools (layout and
>> presentation focus) to do document editing (content, semantics, structure
>> focus) - this causes real problems with document maintenance.
>> (any and all dissenting opinions welcome - please!)
>>
>> A specific example: The Service Assessment Criteria (SAC) are maintained
>> in Word. The Track Changes feature is used to try and capture change
>> records in the document. But our power-users take the Word version and
>> immediately convert it to spreadsheets to do compliance assessments. IAWG
>> has manually created an xls version of the SAC that was current at the time
>> - but that's only a work around.
>>
>> There is no (simple-ish) way to automate different publication formats
>> with this use of Word format as the canonical source. Yes, I know there are
>> scripts and conversion tools available - but the Word source uses format
>> styling to capture semantic structures (e.g. "applies to LOA level x" etc)
>>
>>
>> So that's why I'm asking the question of using a structured document
>> format/tool for the master versions, and using a lightweight markup
>> rendering in something like github to do community input/maintenance...
>>
>>
>> andrew.
>>
>>
>> BTW nice artwork! I'm very glad that doc editing tools have progressed
>> since then. Seems like a difficult format to correct typos   ;-)
>>
>>
>>
>>
>> *Andrew Hughes *CISM CISSP
>> Independent Consultant
>> *In Turn Information Management Consulting*
>>
>> o  +1 650.209.7542
>> m +1 250.888.9474
>> 1249 Palmer Road,
>> Victoria, BC V8P 2H8
>> AndrewHughes3000 at gmail.com
>> ca.linkedin.com/pub/andrew-hughes/a/58/682/
>> *Identity Management | IT Governance | Information Security *
>>
>> On Wed, Sep 14, 2016 at 9:25 AM, Eve Maler <eve at xmlgrrl.com> wrote:
>>
>>> DocBook (or DITA, which it seems is more popular for tech doc these
>>> days) is an XML format and requires XML editing. What editing environment
>>> are you thinking of? XMLmind is probably one of the very few reasonable
>>> choices (it's what I use for editing xml2rfc), but it's still not for the
>>> faint of heart, and it's not free if you want even a minimally "styled"
>>> interface:
>>>
>>> http://www.xmlmind.com/xmleditor/
>>>
>>> Their screenshot of a styled view of a DocBook document:
>>>
>>> http://www.xmlmind.com/xmleditor/screenshots/styled_view.png
>>>
>>> My old cross-stitched saying about DocBook: :-)
>>>
>>> http://www.snee.com/xml/xml2004art/pages/07-docbook-pearl-2.htm
>>>
>>>
>>>
>>>
>>> *Eve Maler*Cell +1 425.345.6756 | Skype: xmlgrrl | Twitter: @xmlgrrl
>>>
>>>
>>> On Wed, Sep 14, 2016 at 6:10 PM, Andrew Hughes <
>>> andrewhughes3000 at gmail.com> wrote:
>>>
>>>> Getting there...
>>>>
>>>> Kantara is piecemeal right now which makes it very hard.
>>>>
>>>> andrew.
>>>>
>>>> *Andrew Hughes *CISM CISSP
>>>> Independent Consultant
>>>> *In Turn Information Management Consulting*
>>>>
>>>> o  +1 650.209.7542
>>>> m +1 250.888.9474
>>>> 1249 Palmer Road,
>>>> Victoria, BC V8P 2H8
>>>> AndrewHughes3000 at gmail.com
>>>> ca.linkedin.com/pub/andrew-hughes/a/58/682/
>>>> *Identity Management | IT Governance | Information Security *
>>>>
>>>> On Wed, Sep 14, 2016 at 8:54 AM, John Wunderlich <john at wunderlich.ca>
>>>> wrote:
>>>>
>>>>> I'd be more concerned with a clear articulation of an authoring,
>>>>> collaboration and publishing workflow and nailing down the tools for each
>>>>> stage and the transitions between stages. If that's clear, I'm willing to
>>>>> learn the tools and processes for the stages that I will engage in.
>>>>>
>>>>> The problem for me would be a lack of clarity or direction so that at
>>>>> any stage in workflow I don't know what tool (or tools) I should be using.
>>>>>
>>>>>
>>>>> Sincerely,
>>>>> John Wunderlich
>>>>> @PrivacyCDN <https://twitter.com/PrivacyCDN>
>>>>>
>>>>> Call: +1 (647) 669-4749
>>>>> eMail: john at wunderlich.ca
>>>>>
>>>>> On 14 September 2016 at 09:08, Andrew Hughes <
>>>>> andrewhughes3000 at gmail.com> wrote:
>>>>>
>>>>>> Hi LC - another question about tools and document formats and markup
>>>>>> languages...
>>>>>>
>>>>>> DocBook
>>>>>> LaTeX
>>>>>>
>>>>>> Do either of those tools/formats strike terror in you? If so, please
>>>>>> let me know.
>>>>>>
>>>>>> I'm just exploring options in the space, so don't panic yet.
>>>>>>
>>>>>> If you haven't guessed, I'm thinking of better ways to store,
>>>>>> maintain and publish the Kantara ID Assurance Framework documents. These
>>>>>> include the Service Assessment Criteria - a highly structured set of
>>>>>> criteria that have many internal and external cross linkages. Also includes
>>>>>> 'normal' explanatory documents. Also includes normative narrative documents
>>>>>> - policy documents if you like.
>>>>>>
>>>>>> My early thought is to use DocBook (an OASIS standard) to maintain
>>>>>> the canonical master versions. A variety of output formats would be
>>>>>> available: .docx, .pdf, .xlsx (for some), .html
>>>>>>
>>>>>> A markdown-flavour rendering of the master document would be posted
>>>>>> to a github project for ongoing issue tracking and community input.
>>>>>>
>>>>>> Am I crazy for looking at this tool chain?
>>>>>>
>>>>>> *Andrew Hughes *CISM CISSP
>>>>>> Independent Consultant
>>>>>> *In Turn Information Management Consulting*
>>>>>>
>>>>>> o  +1 650.209.7542
>>>>>> m +1 250.888.9474
>>>>>> 1249 Palmer Road,
>>>>>> Victoria, BC V8P 2H8
>>>>>> AndrewHughes3000 at gmail.com
>>>>>> ca.linkedin.com/pub/andrew-hughes/a/58/682/
>>>>>> *Identity Management | IT Governance | Information Security *
>>>>>>
>>>>>> _______________________________________________
>>>>>> LC mailing list
>>>>>> LC at kantarainitiative.org
>>>>>> http://kantarainitiative.org/mailman/listinfo/lc
>>>>>>
>>>>>>
>>>>>
>>>>>
>>>>> This email and any files transmitted with it are confidential and
>>>>> intended solely for the use of the individual or entity to whom they are
>>>>> addressed. If you have received this email in error please notify the
>>>>> system manager. This message contains confidential information and is
>>>>> intended only for the individual named. If you are not the named addressee
>>>>> you should not disseminate, distribute or copy this e-mail. Please notify
>>>>> the sender immediately by e-mail if you have received this e-mail by
>>>>> mistake and delete this e-mail from your system. If you are not the
>>>>> intended recipient you are notified that disclosing, copying, distributing
>>>>> or taking any action in reliance on the contents of this information is
>>>>> strictly prohibited.
>>>>>
>>>>
>>>>
>>>> _______________________________________________
>>>> LC mailing list
>>>> LC at kantarainitiative.org
>>>> http://kantarainitiative.org/mailman/listinfo/lc
>>>>
>>>>
>>>
>> _______________________________________________
>> LC mailing list
>> LC at kantarainitiative.org
>> http://kantarainitiative.org/mailman/listinfo/lc
>>
>>
>>
>> _______________________________________________
>> LC mailing list
>> LC at kantarainitiative.org
>> http://kantarainitiative.org/mailman/listinfo/lc
>>
>>
>
>
> This email and any files transmitted with it are confidential and intended
> solely for the use of the individual or entity to whom they are addressed.
> If you have received this email in error please notify the system manager.
> This message contains confidential information and is intended only for the
> individual named. If you are not the named addressee you should not
> disseminate, distribute or copy this e-mail. Please notify the sender
> immediately by e-mail if you have received this e-mail by mistake and
> delete this e-mail from your system. If you are not the intended recipient
> you are notified that disclosing, copying, distributing or taking any
> action in reliance on the contents of this information is strictly
> prohibited.
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://kantarainitiative.org/pipermail/lc/attachments/20160914/7e2bd25c/attachment-0001.html>


More information about the LC mailing list