kit-data-manager / kit-data-manager/ro-crate-java

Missing points in documentation

Open
#8 1 comment 0 reactions 0 assignees View on GitHub
documentation
Dominant language
Java
Stars
5
Forks
4
PR merge metrics
No merged PRs in 30d

Description

The API is documented by examples and javadocs (the non-trivial-parts at least) and is pretty straight forward. But there is space for improvements, as far as I can see:

## Developer docs

Parts of this are also interesting for users:

- [ ] How is import different from export, which class members store what in which case?
- [ ] How are invalid crates being handled on import? What is being tolerated (with warnings), what kind of invalid crates can we not import?
- [ ] When exactly are which parts being validated against what?
- [ ] We need a contribution.md which explains also the principles to ensure contributions are consistent (e.g., what to consider in builders etc)
- [ ] we need a release process to be documented and possibly tooling for it. Somesy can be used to keep the citation.cff up-to-date with another file, but gradle.properties is not yet supported. We can either use some script to invoke instead of gradle release with all required syncing boilerplate, and possibly contribute to somesy.

## User docs

- [ ] We need a better Getting Started Guide, see for example #41
- [ ] Arrays as properties, see #216

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reviewing the checklist and the references to issues #41 and #216, then inspect the existing examples and javadocs. The work spans import/export behavior, invalid-crate handling, validation, contribution guidance, release process, Getting Started, and arrays as properties. Done requires documenting the selected topics and clarifying the release tooling or process.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
20/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.