Recorded spec-up training session

[kimdhamilton]

Per H&T request, we need guidance for newcomers to spec-up. Let's have a session and record it for our future selves

[ankurdotb]

Splitting this into short-term and long-term ideas. I can totally see how spec-up can be confusing if you're not a developer, since it requires setting up NodeJS environments and being familiar with command line.

Short-term

1. Record a video with explainer. I wonder whether we should do this using a tool like Trupeer, which allows for recording videos, and then uses AI to create a step-by-step document with screenshots and written content that can be exported to Markdown.
2. Have a channel in Slack where people can ask specifically for guidance. I'm not sure if this needs to be spec-up related specifically, but could be something like #ask-for-help on DIF Slack where it's considered okay and normal to ask questions. Besides Daniel, who else could be answering questions here?

Long-term

This section can be converted to a sub-issue or separate issue. These are two differing approaches outlined below.

Spec-up automation?

1. One thought is if instead of requiring people to set up spec-up themselves on their own machines, can it be reconfigured so that it's a Github Action and people provide just Markdown. E.g.
   1. People press a button and enter some information which executes a Github Action to setup a repo from the spec-up template. I'm thinking of examples like the "Deploy to Vercel" on repos
   2. From that point on, they just edit / commit Markdown files, and a Github Action on-push does the work necessary that any spec-up scripts do.

Considering simpler alternatives?

1. Even with automation as described above, editing will still likely remain a technical and challenging process, just with Markdown. Technical people are familiar with it, but the learning curve for anyone else is quite steep.
2. Tools like Notion, Confluence (which TOIP and EBSI) use are nice, but they have expensive per-seat licensing and expensive.
3. There are tools/templates which allow writing in Markdown and publishing to Github Pages (one-way sync)
4. One tool I've had success with in the past is Gitbook. Gitbook is a hosted Docusaurus service, which allows connecting to a Github repository with two-way sync:
   1. People who are familiar with Github and Markdown and commit to the repo, and Gitbook takes this to publish to a site (e.g., docs.cheqd.io is built like this)
   2. People who aren't familiar with Github/Markdown have a WYSIWYG editor on Gitbook, and the resultant Markdown is pushed to Github.
5. We may need to create a custom theme/edit an existing Gitbook theme to match what the outputs currently look like. Less to build overall compared to the one above though.

This option above is more a question of whether we want to keep using spec-up long-term.

[kimdhamilton]

Great write-up, thanks Ankur!

Proposal for TSC review/discussion:

• Record a training session and make it available (Question: can Daniel B run the demo?)
• Set up slack or discord channel (Question: add all of TSC? Get volunteers?)
• Review short- and long-term thoughts with TSC; track any follow-up action items

[kimdhamilton]

1/22 discussion

• Could consider a hackmd-like extension with a wysiwyg experience
• Daniel to demo to Matt

[ankurdotb]

Additional ideas:

• NotebookLM to go document it with FAQs, something that can be queried / inspected
• Labs might be higher velocity in new members who have never used Spec-Up