Workshop Spec-Up-T

Intro and non-technical roles

What is Spec-Up-T?

  • Static webpage generator
  • a versioned glossary
  • a single file specification
  • a pdf generator
  • a terminology engine

What do you see as a normal human being?

A specification document with lots of visuals and a glossary.

Why Spec-Up-T?

…and not something else.

  • "Easy-peasy" (Daniel Buchner, DIF)
  • Portable
  • Open source
  • Free
  • Markdown based with a few extra tricks
  • consensus building

For Who?

Can you imagine? You could just write

Markdown +

[[DEF:]], [[REF:]], [[XREF:]]

and be a Spec-Up-T master?!

It is true, but as soon as you get addicted to Spec-Up-T you'll need these skills:

  • use a command line
  • understand directory structures of your own data
  • understand one or two configuration files
  • know how to use git and github, and understand what github actions does to you and for you :)

Why so terribly complicated?? -> authenticity, version management, consensus building

Where to start?

Here

How to use ->

A. Use definition

  1. Go to the Spec-Up-T glossary, where the definition is listed
  2. Copy the persistent URL
  3. Paste the persistent URL, save and publish

Why Spec-Up-T? -> authenticity, version management

B. Amend a definition

Follow A.

  1. Add text to the definition, save and publish

Agent

Because ToIP uses this definition of agent, we'd like to say that we have totally different opinion on agent.

[[def: Agent]]
Because ToIP uses this definition of [[xref:ToIP, agent]], we'd like to say that we have totally different opinion on agent.

How will you do your maintenance on this definition? -> you would need your own repo and installation of Spec-Up-T

5-minute task

Send a message in Slack CTWG discussing a term definition as a response to my latest post today.

C. Create your own terminology using Spec-Up-T

Why Spec-Up-T? -> version management

Subs:

  1. Know who did what
  2. Snapshots in uninterrupted commit history
  3. Auditable: differences analysis

Apart from the following nice to have's:

  • open source
  • free
  • permanent URL copy
  • search
  • one index.html file
  • lowest web hosting requirements as possible

Process

Follow A. en B. above.

  1. Get a git-based version management environment, create a repo there
  2. Install Spec-Up-T
  3. etc.

This is too much to show; use as a memory card:

Website: Show UI

  • collapse / expand terms
  • anchors
  • back to top
  • search (literal string match)

Website: Show Functionality

  • pop ups with defs
  • enter token input

Website: Show “Underwater Screen” (Web Inspector)

  • GitHub API token rate limit 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
  • Simulate error message: notyf.error('GitHub rate limit exceeded. See documentation for more info.')

STEP 2: Installation

Command Line Interface (CLI)

  • Installation procedure (replace blockchainbird with kordwarshuis for demonstration purpose)

STEP 3: Content editing

Command Line Interface (CLI) – Editor (IDE) – Website

  • CLI: Run render
  • Website: Show website buttons (no xrefs yet)
  • CLI: Start menu
  • CLI: Show documentation
  • CLI: Run xref
  • Website: Show buttons (xrefs added)
  • Website: Show help
  • CLI: Run pdf
  • Website: Show diff
  • IDE: Edit test1 aal
  • IDE: Add xref: ~ Xref example: [[xref: test-2, ACDC]]
  • CLI: Run xref
Select a repo