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

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

From: Paola Di Maio <paola.dimaio@gmail.com>
Date: Mon, 1 Jun 2020 07:42:02 +0800
Message-ID: <CAMXe=SoBOgs_ArdZXxZU71pK90YFTu6RDNma98oOP6OwCxotFg@mail.gmail.com>
To: Sebastian Samaruga <ssamarug@gmail.com>
Cc: ProjectParadigm-ICT-Program <metadataportals@yahoo.com>, W3C AIKR CG <public-aikr@w3.org>, carl mattocks <carlmattocks@gmail.com>
Thank you Sebastian
but are these open standard? (can iso standards be downloaded and used or
is it only available for members)

please start a page to maintain this list and start extrapolating
structural elements that we
may want to reuse/reference in our  work. would be nice to produce
something like a template
or a form

also in relation to parser, if you are inclined to learn, please find
learning resources and maintain a list
this group uses zotero

On Mon, Jun 1, 2020 at 5:54 AM Sebastian Samaruga <ssamarug@gmail.com>
wrote:

> OMG MOF XMI (www.omg.org) standards stack.
>
> REST HATEOAS HAL (http://stateless.co/hal_specification.html). Swagger /
> GraphQL.
>
> OpenAPI (https://swagger.io/specification/).
>
> Domain Driven Development. Naked Objects.
>
> Apache Isis: isis.apache.org. OData.
>
> Web Services WS-* stack.
>
> ISO 13250.
>
> ISO 15926.
>
> On Thu, May 28, 2020, 7:21 PM ProjectParadigm-ICT-Program <
> metadataportals@yahoo.com> wrote:
>
>> This looks VERY PROMISING indeed. As I indicated earlier, in the Smart
>> City framework I am fleshing out in an article, the interaction processes
>> between component complex adaptive systems are important. The proposed
>> roadmap for StratML we are creating would focuses on more on qualitative
>> aspects than the actual data objects, software structures,architectures.
>>
>> And qualitative requirements can be perfectly made visible in flowchart
>> diagram protocols, which are already in use in life and bio sciences and
>> medicine.
>>
>> This also reiterates the need to use more generalized tools e.g. instead
>> of KAIROS AND Apache UIMA.
>>
>> Milton Ponson
>> GSM: +297 747 8280
>> PO Box 1154, Oranjestad
>> Aruba, Dutch Caribbean
>> Project Paradigm: Bringing the ICT tools for sustainable development to
>> all stakeholders worldwide through collaborative research on applied
>> mathematics, advanced modeling, software and standards development
>>
>>
>> On Thursday, May 28, 2020, 7:59:17 AM ADT, carl mattocks <
>> carlmattocks@gmail.com> wrote:
>>
>>
>>
>> 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 Sunday, 31 May 2020 23:42:54 UTC

This archive was generated by hypermail 2.4.0 : Sunday, 31 May 2020 23:42:55 UTC