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

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

From: Paola Di Maio <paola.dimaio@gmail.com>
Date: Tue, 26 May 2020 10:10:16 +0800
Message-ID: <CAMXe=SoJ70D9andL-ZXF8x_YB5r-0TPenDG4MdjV4u6Hqrp36Q@mail.gmail.com>
To: W3C AIKR CG <public-aikr@w3.org>
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 Tuesday, 26 May 2020 02:11:07 UTC

This archive was generated by hypermail 2.4.0 : Tuesday, 26 May 2020 02:11:08 UTC