- From: Paola Di Maio <paoladimaio10@gmail.com>
- Date: Mon, 1 Jun 2020 08:53:27 +0800
- To: Sebastian Samaruga <ssamarug@gmail.com>
- Cc: W3C AIKR CG <public-aikr@w3.org>
- Message-ID: <CAMXe=Soye2c=2kM6ZOi5OMbbEAVARh1JnWvMQ2H5VhBe3WK3Pg@mail.gmail.com>
Thanks Sebastian This works for you because you have been doing this for some time and know the background When teaching students or individuals from other planets I need to tell them what good software/system documentation is how it is done, at the moment the standard that I know of are ieee I dont think I can expect someone who is trying to share a bit of code to go and download some other software that they are not working on to see how well it is documented and start from there But what I can do, is look around and create a general template based on good practices available as per the many examples that you cite Learning resources are designed to facilitate orientation It would be good to have a standard template to reference which is not language/platform/method dependent I have not seen much OO taught as standalone in the last ten years, but the underlying principles are still around p On Mon, Jun 1, 2020 at 8:39 AM Sebastian Samaruga <ssamarug@gmail.com> wrote: > AFAIK Open Source projects "standards" (protocols, serialization formats, > etc.) "openness" is bound to reference implementations or other whatsoever > implementations licences and their restrictions. > > In other way, for example, OMG UML (Object Oriented software documentation > standard, layered from textual use cases to the ultimate documentation / > specification: code) is "open" in the sense that tools sharing they > interchange mechanism (XMI / MOF) understand each other models, and there > are a lot of those tools. > > So, ultimately, you could better download tools which "understand" > standards. That's why I'm copying semantic-web list. I think that Semantic > Web (RDFS / OWL) mechanisms provides the ultimate layouts and formats for > data (models built upon standards) exchange. > > And lastly, for me the path between StratML to and from semantic > statements feels like the initial steps for the realization of what was the > attempt of OMG MDA, starting in a declarative textual domains descriptions > for further (automated) transformations until reaching the final > documentation: code. > > Declarative business domains applications and integrations has come a long > way: HyTime (sic). We already have a bunch of standards around yet, > apologies for the nostalgic comments. > > Regards, > Sebastián. > > On Sun, May 31, 2020, 8:42 PM Paola Di Maio <paola.dimaio@gmail.com> > wrote: > >> 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 Monday, 1 June 2020 00:54:21 UTC