EDC Documentation

[juliapampus]

As discussed, we want to improve existing documentation, provide appropriate touch points for the relevant stakeholders, and identify missing documentation. The following personas should help with this.

This discussion is also referring to eclipse-edc/Connector#580.

Currently, we provide the following entry points:

• GitHub pages
  • Renders all markdown files places within each repository
  • Lists all components
  • Introduction into the project
  • Links to known friends, contribution information, and hands-on material
• GitHub organization profile
  • Links to decision records, contribution guidelines, developer documentation
  • On-boarding material: MVD, samples, YouTube
• Component repositories: docs folder
• .github repository
  • Developer documentation
  • Contribution guidelines & material
  • Known friends list
  • Templates

[juliapampus]

Persona 1: Developer

Group: End-user (can become a contributor)
Job title: Software Developer, or similar
Skills:

• Experienced with software development/deployment
• Experienced with provided technologies (Java, Gradle)
• Dataspace knowledge

Tasks:

• Get familiar with the EDC
• Build/setup a dataspace component
• Develop own extensions

Needs:

• Hands-on material (samples, videos, mvd)
• Guidance on the framework (extensions, configurations, dependency resolution, version catalogs)
• Interface descriptions (code-level, OpenApi)
• Javadocs
• Release notes (changelog)

[juliapampus]

"EDC as a blackbox"

In scope:

• Asset structure
• Config structure
• How to create your own connector

[juliapampus]

Persona 2: Decision Maker

Group: End-user
Job title: Software Architect, or similar
Skills:

• Technical kowledge
• Experiences in software development
• Dataspace knowledge
• Familiar with software documentation methods

Tasks:

• Get an overview of the project
• Estimate costs and benefits of using the EDC vs. Starting own developments from scratch
• Requirements engineering
• Create report

Needs:

• Architecture overview
• List of features
• Used standards
• Roadmap, release information
• Statements/Information on how the EDC project relates to other initiatives

[juliapampus]

Persona 3: Contributor

Group: Contributor
Job title: Software Developer, or similar
Skills:

• Experienced with software development/deployment
• Experienced with provided technologies (Java, Gradle)

Tasks:

• Get familiar with the EDC
• Develop features, bug fixes, etc.
• Contribute code

Needs:

• Hands-on material (samples, videos, mvd)
• Guidance on the framework (extensions, configurations, dependency resolution, version catalogs)
• Interface descriptions (code-level, OpenApi)
• Javadocs
• Contribution guidelines
• Testing strategies

[juliapampus]

Add-on to Persona 1:

• Community guidelines
• coding style
• how to become a contributor/committer

[juliapampus]

Persona 4: Newbie

Group: End-user
Job title: Software Developer, Researcher, or similar
Skills:

• Experienced with software development/deployment
• Experienced with provided technologies (Java, Gradle)
• No dataspace knowledge

Task:

• Get familiar with the EDC
• Estimate the fit into projects

Needs:

• Architecture overview
• List of features
• Used standards
• Hands-on material (samples, videos, mvd)

[juliapampus]

Approach: merge with Persona 1 (provide a section that an experienced developer can skip)

[juliapampus]

ToC GitHub Pages

• Home (landing page)
  • High-level description of the project
• Getting Started
  • Two line description of components
  • Diagram to visualize the relations of the components
  • Hands-on (developer documentation) @paullatzelsperger create draft docs: add TOC for the developer handbook docs#80
    • text
    • list of links
  • Contributing
  • Architecture documentation
• Components
  • README following the same structure
• Documents
• Known Friends

TODOs

• Work on general documentation (create PR in https://github.com/eclipse-edc/docs)
• Review/update READMEs of each component repository
• Review existing documentation