W3C home > Mailing lists > Public > public-aikr@w3.org > May 2020

Re: Software documentation conventions/open standard (note work to be done)

From: carl mattocks <carlmattocks@gmail.com>
Date: Thu, 28 May 2020 06:57:59 -0400
Message-ID: <CAHtonu=Tf3r1gZDPBu0w1ukLD-fRHQTYOjEsv4gBbqEoc-69BA@mail.gmail.com>
To: W3C AIKR CG <public-aikr@w3.org>
Suggest a useful AIKR extension to StratMl would be oriented towards a
measurable use of TRUST Protocols - which the CG could define as part of an
AIKR Trust Protocol Ontology

For reference see  The Open Trust Protocol (OTrP)
https://tools.ietf.org/id/draft-ietf-teep-opentrustprotocol-00.html

Carl

It was a pleasure to clarify


On Thu, May 28, 2020 at 2:21 AM Paola Di Maio <paoladimaio10@gmail.com>
wrote:

> Chris
> it would be a great start if we could modify stratml a little to produce
> an open standard for technical documentation. I have checked today and
> there seems to be on app to automate technical documentation/manual, so you
> could even end up selling/licensing it
> Let's work on this too!
>
>
>
>
>
>
>
> On Thu, May 28, 2020 at 1:59 PM Chris Fox <chris@chriscfox.com> wrote:
>
>> My intuition is that StratML would be good for documenting *what *a
>> software, process, architecture etc. aims to achieve. It would be less good
>> a documenting how it actually works.
>>
>> I say this as someone who is familiar with both StratML and with software
>> development, process design and architectures.
>>
>> On Thu, 28 May 2020 at 01:01, Paola Di Maio <paola.dimaio@gmail.com>
>> wrote:
>>
>>> Well, documentation can be of software, of process, of architecture, of
>>> product and of course of standard
>>> the ultimate documentation is a technical manual which goes into detail
>>>
>>> To answer your question we would have to carry out a study -
>>> ie compare existing technical documentation standards to stratml
>>> structure/elements
>>> and identify what may be missing
>>>
>>> My guess is that with some adaptation (adding sections) stratml could be
>>> used to produce technical documentation as well and it could be a good way
>>>
>>> I m now thinking what is the best way to generate an open standard for
>>> technical documentation
>>> with the least possible effort (given the scarcity of resources)
>>> and would not rule out a stratml approach if the group is interested to
>>> pursue that venue
>>>
>>> Thinking further one could use stratml like features to automatically
>>> generate technical manuals too
>>> maybe that could be turned into a product itself
>>>
>>> p
>>>
>>>
>>> On Wed, May 27, 2020 at 9:46 PM carl mattocks <carlmattocks@gmail.com>
>>> wrote:
>>>
>>>> Paola
>>>>
>>>> Would you accept that an AI Strategist plan for an AI System  crafted
>>>> /published, via StratML, would be a good use of an open standard for
>>>> documentation?
>>>>
>>>> Carl
>>>>
>>>>
>>>> It was a pleasure to clarify
>>>>
>>>>
>>>> On Mon, May 25, 2020 at 10:11 PM Paola Di Maio <paola.dimaio@gmail.com>
>>>> wrote:
>>>>
>>>>> Thanks for starting to share snippets of ideas and code, such as krid
>>>>> and parser for stratml
>>>>>
>>>>> //I come from a systems documentation background - I teach a course as
>>>>> I learned the
>>>>> trade from an emeritus :-)//
>>>>>
>>>>> May I remind the list that it is good practice to document and share
>>>>> work being done in ways
>>>>> that it can be intelligible . (should say what it is, how to use it
>>>>> etc)
>>>>>
>>>>> (If something cannot be understood or does not make any sense because
>>>>> it is incomplete
>>>>> or truncated or devoided of context, could be ignored or generate
>>>>> revulsion)
>>>>>
>>>>> I note the lack of open standards for software documentation as a
>>>>> possible to be done/long term deliverable
>>>>> for this or other CGs (work to be done?)
>>>>> If someone knows of an open standards for software documentation,
>>>>> please share it here!
>>>>>
>>>>> Here some pointers,
>>>>>
>>>>> 1. Good practices in documenting software/code
>>>>>
>>>>> https://blog.prototypr.io/software-documentation-types-and-best-practices-1726ca595c7f
>>>>>
>>>>>
>>>>> 2. Good example of adoption of good practice Open Stack
>>>>> https://docs.openstack.org <https://docs.openstack.org/ussuri/>
>>>>>
>>>>> Please consider sharing ideas and software in a way that it can be
>>>>> understood and used
>>>>> by others on the list, thanks!!
>>>>>
>>>>> pdm
>>>>>
>>>>>
>>>>>
>>>>>
>>
>> --
>> Chris Fox
>> Chris C Fox Consulting Limited
>>  chris@chriscfox.com
>>  +44 77 860 21712
>> <http://www.chriscfox.com>   [image: https://calendar.x.ai/chriscfox]
>> <https://calendar.x.ai/chriscfox>
>> <http://www.linkedin.com/in/chriscfox>
>> <http://www.twitter.com/chriscfox>
>> <http://www.facebook.com/pages/StrategicCoffee/102920468071>
>> <https://join.skype.com/invite/oxuJFtEDlgQw>
>> Have you tried https://www.StratNavApp.com <https://www.stratnavapp.com/>,
>> the online collaborative tool for strategy development and execution?
>>
>> Chris C Fox Consulting Limited is registered in England and Wales as a
>> Private Limited Company: Company Number 6939359. Registered Office: Unit 4
>> Vista Place, Coy Pond Business Park, Ingworth Road, Poole BH12 1JY
>>
>
Received on Thursday, 28 May 2020 10:58:52 UTC

This archive was generated by hypermail 2.4.0 : Thursday, 28 May 2020 10:58:53 UTC