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: Thu, 28 May 2020 08:00:02 +0800
Message-ID: <CAMXe=SqUQ4fwHXvcVJ1A1Spj75_XfvLoOya0L_sJpeWhVhxbNw@mail.gmail.com>
To: carl mattocks <carlmattocks@gmail.com>
Cc: W3C AIKR CG <public-aikr@w3.org>
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
>>
>>
>>
>>
Received on Thursday, 28 May 2020 00:00:53 UTC

This archive was generated by hypermail 2.4.0 : Thursday, 28 May 2020 00:00:54 UTC