search

FuReSH / tool-storage-metadata

Metadata and workflows for editing and adding data in the Scholarly Makerspace tool storage
Creative Commons Attribution Share Alike 4.0 International
1 stars 2 forks source link

readme

⚠️ Notice

This repo was used to build the open wikidata-based tool registry and is no longer up-to-date. Please use the Wikidata:Wikiproject DH Tool Registry for more information.

pre-commit.ci status Last check of YAML test data

Dieser Ordner enthält die Daten zu unserem metaphorischen Werkzeugregal. Dahinter steht die Idee die Metaphern von Werkzeugen, Werkzeugkoffern, Werkzeugregalen, Blackboxes mit physischen Objekten pädagogisch nutzbar zu machen. So gibt es in unserem Scholarly Makerspace ein Werkzeugregal in dem sich Werkzeugkisten und Blackboxes befinden. Werkzeugkisten sind nach Typen (Kategorien) von Werkzeugen, z.B. "Programmiersprachen" oder "Dateiformate", und Blackboxes nach Themen, z.B. "Web Scraping" oder "Distant Reading", gepackt.

Der Begriff des Werkzeuges ist hier so weit wie möglich gefasst und umfasst Methoden, Konzepte, Software, Sprachen, Hardware etc.

To do

Ordnerstruktur

Set-up für dieses Repo

Der Kern unserer Infrastruktur sind YAML Dateien. Da YAML ein Superset von JSON ist, lassen sich YAML Dateien mit JSON schemas validieren. Dafür muss in der Software unserer Wahl ein Linter eingerichtet werden.

SublimeText

In Sublime Text stellt das Package SublimeLinter eine Plug-in Infrastruktur für Linter zur Verfügung. Diese müssen aber für alle Sprachen einzelen installiert werden.

Für YAML gibt es das Package SublimeLinter-contrib-yamllint, das ein Interface zu der Python library [yamllint]() bereitstellt. Letzteres kann mit pip install yamllint installiert werden. Allerdings biete yamllint keine Validierung mit JSON schemas

VSCode

In VSCode gibt es eine YAML Extension, die die notwendige Funktionalität bietet. Siehe zur Einrichtung auch die Dokumentation auf GitHub: vscode-yaml

Werkzeuge

Dabei gibt es pro Werkzeug eine YAML Datei. Diese wird über ein JSON Schema validiert und muss neben einem Werkzeugnamen eine Wikidata ID enthalten und mit mindestens einer unserer lokalen Kategorie kategorisiert sein. Daneben kann sie Kurzbeschreibung, weiterführende Links, Links zu Icons etc. enthalten. Dafür wird es ein template geben. Um das Auflösen von URLs zu erleichtern, sind die Dateinamen einfach [WERKZEUG].tool.yml also z.B. docker.tool.yml. Dateinamen werden grundsäztlich kleingeschrieben und Lehrzeichen durch Bindestriche ersetzt. Weitere Informationen bzw. andere Arten von Informationen zu Werkzeugen werden in Markdown-Dateien (.md) mit funktionalen Zusätzen zum Dateinamen festgehalten, wie z.B. _tutorial. Entwürfe werden mit dem Zusatz _draft versehen.

Unser Werkzeugbegriff

Das folgende Diagramm visualisiert diese Beziehungen und gibt Wikidata Items und Properties an

flowchart LR
    %% nodes
    theory(Theory\nQ17737)
    method(Method\nQ1799072)
    software[Software\nQ7397]
    hardware[Hardware\nQ3966]
    language[Language\nQ9143]
    concept(Concept\nQ151885)
    format[file format\nQ235557]
    Q494823[data format\nQ494823]

    %% edges: note that the layout does not imply hierarchies
    theory -->|informs| method
    method -->|is implemented\nby| software
    software -->|"has use (for)\nP366"| method
    method & format & language -->|uses| concept
    software -->|requires| hardware
    software -->|is written in\nP277| language
    software -->|interaction requires| language
    software -->|reads\nP1072| format
    software -->|writes\nP1073| format
    format -->|subclass of| Q494823

    %% classes
    classDef software fill:#ECA7F9
    classDef language fill:#F24726
    classDef concept fill:#F9C710
    classDef format fill:#8BCA4B
    classDef method fill:#7ce5cb
    class method method
    class software software
    class concept concept
    class format,Q235557,Q494823 format
    class language language

YAML

Beispiel einer minimalen YAML Datei

---
# yaml-language-server: $schema=../schemas/tool.schema.json
name: Docker
wikidataId: Q15206305
category:
  - software

Setkarten

Jedes Werkzeug wird durch eine Setkarte dargestellt.

Setkarte für ein Werkzeug

Jede Setkarte enthält die folgenden Informationen:

Die Farbgebung codiert eine basala Kategorisierung. Die Verteilung der Informationen auf Vorder- und Rückseite steht noch nicht fest.

Blackboxes können ähnliche Setkarten bekommen

Setkarte für eine Blackbox

Erstellung der Setkarten

Wir stellen uns einen mehrheitlich automatisierten Prozess der Erstellung der Setkarten auf der Basis der Informationen in unserer tool registry vor, dabei wird jedes Werkzeug mit einer einzelnen YAML Datei beschrieben.

Schematische Darstellung der Infrastruktur hinter den Setkarten

Blackboxes

Blackboxes sind vor allem Methoden und Konzepte und nicht einzelne Werkzeuge, also "Web Scraping" und nicht "Python". Für jede Blackbox gibt es Input / Output und eine Menge Inhalt. Jede Blackbox hat auch einen Setkarte im Werkzeugregal, aus der Informationen gezogen werden können. Wie gehabt, werden Blackboxes mit YAML-Dateien beschrieben. Dazu gibt es eine eine visuelle Übersicht über den Inhalt und wie er zusammengehört. Dieser macht von der schematischen Ansicht unserer Setkarten Gebrauch.

Blackbox: Web Scraping

Die YAML-Datei kann entweder ein vollständiges Subset unserer tool directory sein oder stark reduziert. In letzterem Fall muss sie für die Menschenlesbarkeit immer auch einen Namen enthalten. Details sind in den Dokumenten zur technischen Infrastruktur spezifiziert.

Scholarly Makerspace tool storage metadata by Universitätsbibliothek of Humboldt-Universität zu Berlin is licensed under CC BY-SA 4.0