[KI-LC] Another doc authoring tool question

John Wunderlich john at wunderlich.ca
Wed Sep 14 12:44:46 CDT 2016


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/97427613/attachment-0001.html>


More information about the LC mailing list