Job stories for editor guide(s) (what 'How to...?' questions are wanting to be answered?)

[rufuspollock]

Job stories for editor guide(s) (what 'How to...?' questions are wanting to be answered?)

Personas

Who are we writing for?

We are writing for non-technical people i.e. not developers. That said, in most tutorials we are assuming ...

• A basic knowledge of markdown
• Already using github

Later we will add support for learning these too.

If writing for devs we will flag that

If we are writing for a developer/technical editor we will flag that and say e.g. "dev editor" or something like that ...

Personas List

Our personas and their skill levels.

Skill	Newbie	Markdown-aware	Dev	For Flowershow/PortalJS
Markdown	❌	✅	✅	✅
Git	❌	?	✅	✅
Obsidian	❌	?	✅	✅
Hackmd	❌	❌	✅	✅
Backend Knowledge	❌	❌	✅	✅ ✅
JAMStack	❌	❌	✅	✅

• markdown (levels)
  • 0: you don't know what markdown is
  • 1: you know what markdown is and have seen it but aren't familiar
  • 2: ...
  • 3: you are familar with markdown formatting. You could use a markdown editor and know where markdown would be used.
• markdown plus: you know markdown plus the advanced features like footnotes and tables, code blocks etc
• git(hub):
  • 0: you don't know what git or github are
  • 1 You know what it is, the different functionality it can provide and why it is used, and (some of) the associated programs that can be used with it
  • 2 ...
  • 3
• wordpress: editing previous knowledge related to the backend of programs for visual layout and confidence in navigation i.e. wordpress
• obsidian: none
• hackmd: none?
• any coding/scripting (used in Brevo) (Javascript?): none
• JAMStack: you are familiar with with JAMStack (Javascript + API + Markdown) websites including their construction and deployment. i.e. you are a dev with at least enough knowledge to build and deploy such a site and probably with some javascript knowledge.

Job Story

When writing documentation and guide for editing markdown + Flowershow/PortalJS based sites I want job stories so that I know what to prioritize to write and what i should be addressing

Acceptance

• Personas identified
• List of job stories
• Categorize job stories in some useful way
• Prioritized job stories

Tasks

• Create personas or at least identify skill level we are aiming at
• Collect existing needs and job stories
• Brainstorm high level categories

Job Stories

4 high level jobs / journeys

• Website: put content on the web. Create a markdown-based website, update it, add collaborators and discover markdown superpowers 🚀🦸‍♀
• Collections: create and publish collections of things: Create markdown-based "database/catalogs", collaborate on it and publish it ...
• Data: Publish data or data stories. Create markdown-based data catalog/portal/data-rich content, update it and publish it
• Garden: make a knowledge garden. create a markdown-based wiki / knowledge garden with linked notes and more.

And a combo one: (very common actually)

• Publish a site integrating content, collections, data and a garden I want to build a site combining some or all of these features!

And a sixth "meta" story:

• Why FOGM? i.e. why use FOGM rather than e.g. wordpress to address these jobs?

Sharing and Publishing: distinct functionality relevant to each high level job story

For each of the above you have a spectrum of potential sharing that relates to "where" you are doing this:

• Personal: you are just creating for yourself e.g. locally on your machine
• Shared: you want to be able to share the result
• Published: published on the web, for everyone to access

A common user journey goes from personal/local first to sharing to publishing on the web.

graph LR

local[Make local note]
local --> addmore[Add more notes]
addmore --> share[Share with others]
addmore --> publish
share --> publish[Publish as website]

Put text on the web

• I want to put a landing page on the web
  • What is a landing page?
  • Hero
  • Call to action
  • Signup etc
• I want to put up a note / post / article / report
  • Long-form text
  • Author
  • Date
  • ...
• I want to create a blog: essentially article plus one very specific version of "collection of stuff"

Publish Collections

• I want to publish a collection or catalog of stuff: on its own or embedded elsewhere e.g. a portfolio, a data catalog, my favorite movies, a list of books, a list of people ...
  • List of items
  • A browse/search page
  • NB: these can grow more complex e.g. multiple lists of items which connect e.g. organizations and the topics they work on

Publish Data

TODO

Knowledge garden

• I want to create a knowledge garden/wiki: i.e. docs are interlinked

Why use this approach (POGM)?

TODO: still needs refactoring ...

There are lots of ways to address these different needs from classic CMS and blog platforms like wordpress to wikis etc.

However, few of them use markdown (so why use markdown)

Our contention is that a markdown-based approach using PortalJS/Flowershow/Markdown integrated toolkit is really great because ...

• Many fewer once you add markdown requirement.
• And we are offering one specific set of tooling to do this.

❗️ List of howtos to be written

Put text on the web

• How to quickly add a simple Markdown-based page
• How to edit or add Markdown-based pages locally on your computer
• How to quickly edit text on a single Markdown-based page
• How to add images to a Markdown-based page
• How to format a perfect Markdown-based page **💬 we have a basic draft but needs refinement **
• How to quickly create a sandbox website
• How to debug and fix 404 errors
• How to hide a Markdown-based page without removing it from the content folder
• How to add a signup form
• How to theme the website
• How to redirect pages
• How to add tables, charts, or maps
• How to create and use custom React components in Markdown pages?

Knowledge garden

• How to push an Obsidian vault to a GitHub repository

Publish Collections

• (Tutorial) Create a catalog of anything using Markdown files in Obsidian

Collaboration

• How to propose changes to someone else's website

⬇️ LifeItself-specific

• How to add or edit the content on the Life Itself ecosystem page
• How to edit the people page
• How to edit the teams' page

Notes

Nathen https://github.com/orgs/life-itself/discussions/393#discussioncomment-5460864

How to correct a pull request

One thing I keep getting stuck on is how to not include changes into a pull request and to remove those changes as if they didn't happen. For now I just commit and then do the fixes, but this seems inefficient.

Other questions

• How to make two different pulls requests
• How do we symlink pages. And what is symlinking?
• How to update the teams page
• How to use components 💬2023-05-24 relevant for using components provided by that platform
  • How to create and use bespoke components? ✅2023-05-24 ❌ not so relevant as we don't support bespoke components so much
• How to use tailwind
• How to use css
• How to redirect pages

Zaib https://github.com/orgs/life-itself/discussions/393#discussioncomment-5502358

I have learned how to use Obsidian from Nathen, he showed me how to use it and we recorded the video. I followed the video later to create the project pages and people page. The problems I encountered are:

• A clear understanding of the flow of Syncing the Fork, Pull origin, and push origin and creating the pull requests.
• How to add images from Vault
• How to add internal and external links
• how to edit the people page
• The protocols around making edits in Obsidian, for instance, I had to delete the image from the vault when I removed it from one of the pages, I didn't know this from the start.
• Lastly, the protocol around updating the Issues in the "current iteration" in Backlog All.
• On-going Problem: How to fix merge conflicts

I have a clear understanding of these right now, but in the start it was confusing. A walk-through guide in navigating GitHub and Obsidian would be very helpful for people just getting started.

Rufus https://github.com/orgs/life-itself/discussions/393#discussioncomment-5461119

• How to use excalidraw and specifically auto embed the svgs (cf https://github.com/life-itself/diginomics/blob/main/content/notes/combining-pieces.md)
• Why svg over png (if you have a choice)
• Storing image files locally?

[laurenwigmore]

Useful How to's for newer members of the team, or less frequently completed actions

• Add a page with a Hero + Content layout
• How to open new repositories on Obsidian / general How to of where to go for what overview
• How to sync Obsidian so that it represents the actual Github repo
• How to delete old branches
• How to complete a review when you are assigned as a reviewer
• How to add and link an image into a page/post (for example I had an issue with the tenzo 9 blog and the main image showing up on the page) (Lauren to create issue)
• Templates specific to LI section for main pages/posts/layout
• How to find the link to an image in the asset list (if you know the name) so you can drag it into a blog

[rufuspollock]

FIXED. Moved to https://github.com/datopian/makeitmarkdown/blob/main/design.md

DUPLICATE. Merging this back into the parent epic for now. No need for a separate issue.