search

uncefact / spec-jsonld

Exposing the UN/CEFACT vocabulary as web semantics
https://service.unece.org/trade/uncefact/vocabulary/uncefact/
13 stars 5 forks source link

Documentation: Elaborate further documentation on the input, the tool usage and the output of the project #152

Open svanteschubert opened 1 year ago

svanteschubert commented 1 year ago

I would suggest adding more description of

  1. the possible inputs,
  2. the usage of tooling and
  3. the output of this repository:

My first impression and expectations come from the other way around:

  1. I have first seen the website: https://vocabulary.uncefact.org/ likely the output of this project.
  2. I was pointed to this repository to be the tooling to create (the data of) the website.
  3. I am aware of some downloadable artefacts at UN/CEFACT, which might be used as input, like the zipped XLS https://unece.org/trade/uncefact/unccl

I was struggling to reproduce the nice website (or at least the created data from this tooling).

A short overview/description of the repo directories in the root readme would be appreciated as well.

The documentation I found for transforming was here: https://github.com/uncefact/spec-jsonld/tree/main/scripts

Would be nice to be able to reproduce the transformation in its total.

svanteschubert commented 1 year ago

Another docu sub-issue:

The GitHub pages ./docs directory does not seem to be activated: https://uncefact.github.io/spec-jsonld nor https://uncefact.github.io/ can be accessed nor is file https://github.com/uncefact/spec-jsonld/blob/main/docs/tech-spec.md being referenced by the README.md.

svanteschubert commented 1 year ago

I will not create a new issue for this, as it is close to the documentation: the source structure of this project. Please note that I do not mean to be picky (and/or "German") by all these suggestions! These are just mere suggestions, not real issues or bugs... from my perspective a kind of final polishing :-)

  1. I would suggest moving the meeting-minutes folder into the docs (GitHub Pages) folder and reference the folder (mention its existence) at the root README.md file.
  2. The Java build system Maven has a default standard layout, which allows developers to know where to search/expect content. From my expectations, all resources within src/main will be bundled with the deliverable. Test files that are not bundled should be moved from src/main/resources to src/test/resources
  3. I would suggest dropping the two folders "/scripts/transformer" Move the pom.xml to the root directory or if you expect to have more modules in the future create a parent/child pom.xml structure like in the ODF Toolkit.
  4. I need more input on ccts_inbound and json-ld-outbound but these empty folders are in the first place "noise" to newcomers. I am writing a follow-up issue on automated regression testing and will explain more details there.
svanteschubert commented 1 year ago

Some quick observations on the output:

  1. Currently, there is still a "desc" abbreviation for the missing description in https://vocabulary.uncefact.org/rec20
  2. I have no idea what the column "Level Category" and "Status" in https://vocabulary.uncefact.org/rec20 represent. Is it a UN/CEFACT implementation detail?
  3. The "Conversion Factor" is likely better rather explained as "Representation by SI-based units", right? A "Conversion Factor" would be strictly speaking without a unit symbol, right?
  4. For https://vocabulary.uncefact.org/rec20#36 remove the comment "Conversion factor required" as "ft³/(min/ft²)" is a speed equal to "ft/min" being converted to "0,00508 m/s" (should be fixed in the UN/CEFACT data set upstream)