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.
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
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.
Hey there! Seems there isn't any spacing on the left side when opening the site from a phone
For some phones, it makes it hard to read as the screen might curve a bit. Since the right side seems to have a border, it would be nice to have it to on the left!
Feel free to close if the design is intended though!
An inbox for keeping track of outstanding tasks that are currently paused.
Acceptance
The following tasks have been completed (if still relevant)
Tasks
Remove tutorial content from portaljs site and add a redirect to makeitmarkdown (see final acceptance point here)
Remove howtos content from portaljs site and add a redirect to makeitmarkdown (see final acceptance point here)
Transfer any images that we have decided to keep from the portaljs repo to makeitmarkdown (see comment here)
Remove 'content' folder in makeitmarkdown repo and move its contents up a level (see Rufus' comment here) 2024-01-04 UPDATE: Have asked Ola for help on how to do this without breaking links to contents inside the folders
Delete from portaljs (with redirect to makeitmarkdown) β2024-01-03 WONTFIX. I think we should delete only once Makeitmarkdown is complete, as backup in case anything goes wrong or we need to reference something. Added this to #20 to revisit later
Tasks
Fix images so they show up in the migrated blog post
Review and recommend for integration the existing polished documentation we already have - see list below
Acceptance
List what do we already have: url, title and summary β 2023-10-31 see below
What could we integrate? Make recommendations e.g. below ... β 2023-10-31 β we did not have any recommendations at the time
Flag that info for relevant tutorials (in the issue or to team member etc) β 2023-10-31 β i think we did use some parts plus we published directly some parts
Tasks
Review each of these
https://lifeitself.org/ecosystem/contributors-guideTitle: Guide to editing Life Itself ecosystem - Summary: Detailed guide on editing the ecosystem page on Life Itself. Comprehensive with images to signpost
https://web3.lifeitself.org/meta/editingTitle: Editor's guide using Github + Obsidian/code editor - Summary: Guide on editing the Life Itself webpages, including a section for Obsidian/ other code editors
Obsidian Tutorial meeting Recording and TranscriptTitle: Tutorial for editing with Obsidian - Summary: 1.5 hour video with Rufus and Nathen as well as complementary transcript
link to the video that explains the Github and Obsidian workflowπ¬2023-05-24 βοΈ need access from owner (nathen)
β2023-06-06 this tutorial about creating a local catalog with obsidian https://github.com/datopian/markdowndb/tree/main/examples/obsidian-dataviewTitle: Guide to creating catologues with Obsidian - Summary: Detailed guide with images as signposting to create catalogues, using Harry Potter characters as examples
https://datopian.com/playbook/markdownTitle: Information on Markdown - Summary: Short guide to Markdown and the basics to its usage + redirection to more in-depth tutorials
β DONE: Title + Summary for each resource (excluding one with restricted access)
Remove from portaljs.org (and add redirect?) β2023-12-21 WONTFIX. I think we should delete only once Makeitmarkdown is complete, as backup in case anything goes wrong or we need to reference something. Added this to inbox of outstanding tasks to revisit later
Try to locate the underlying markdown file of the page you're trying to access (e.g. through clicking on some link) to see if it exists
2 If it's there, check the spelling
If it's not there, see if you can find it in another place in the repo and adjust the links accordingly
If this didn't help, this might be an issue in your forntend app?
As a new contributor to a Flowershow/PortalJS site (e.g. LifeItself.org), I want to edit an existing page on the website (whose contents are stored on GitHub), i.e. add/change some text, edit/add links to other pages, and/or add images to it so that the page is updated.
What does this contributor know ...?
Assume (but flag) you have edit access to the relevant repo/system (i.e. don't explain the process of getting the access in the tutorial)
Any website that is markdown based with jam-stacky tendencies would be relevant here, not only Flowershow based one
There is going to be a sandbox that readers can use when following the tutorial. A sandbox is a single instance of a simple Flowershow website with a few example pages. Assume this sandbox is already set up including automatic deployment.
Will there be a live preview somewhere? No, not for now.
βοΈ For now, add any terms/concepts explanations in e.g. Obsidian info callouts. They will form the basis of relevant sections in our Contributors Guide in the future.
Create a first editor guide for adding and editing conten to a markdown-based site -- specifically a markdown-based, flowershow-published site and even more specifically a "MOGF" (markdown-obsidian-github-flowershow built site).
Outcome visioning π― (High level acceptance)
A non-dev editor/author at Life Itself or anywhere else has a single online place to go to with (or linking to) sufficient docs to autonomously (i.e. without dev support) ...
Edit lifeitself.org
Create a new blog post
Create a new page
Edit a blog post or page
Create, share and publish a micro-catalog
Create locally
Share with others (privately)
Publish
Create a digital knowledge garden i.e. content + catalogs etc
Plan of work
Prep
The content you are editing has changed. Please copy your edits and refresh the page.
https://app.excalidraw.com/s/9u8crB2ZmUo/14uWaFN0z4C - Docu-thon for Catalogs with Flowershow, PortalJS and MarkdownDB - this has sketches of front page with other more general notes about purpose and approach
Content
The content you are editing has changed. Please copy your edits and refresh the page.
Create a set of materials explaining a markdown-based approach to building websites, taking notes and more. i.e. why and how to use markdown to publish websites, make wikis, create lightweight "databases" and more. "Why markdown-based approach is an awesome alternative to notion and things like that ..."
Check existing materials we can use β 2024-01-05 content from PortalJS guide is largely re-usable
Write primary tutorial π§ 2024-01-08 in progress. Tutorial 1 and Tutorial 2 ready, tutorials 3 and 4 in outline form (Elisa doesn't have the technical knowledge to do tutorial 4)
Tasks
Write-up nextjs example as a great thing to learn from See below under 'Notes'. Have done up to Lesson 3 as this feels like enough to understand the logic.
80% complete on writing out the 'motivation'/what is markdown page (haven't pushed the changes to motivation page to GitHub yet)
Currently working out how to make the 'why use markdown' specific to websites (rather than generic advantages of Markdown, which is what we had on the skeleton)
Have recruited 1 volunteer so far ππ
Questions
Is it okay to reuse most of the material that Ola wrote? Yes
Tutorial 4 is not written and I don't know how to do it... Put a note saying under construction...
Rufus comments
(Note: moved these under 'tasks' above)
Move everything at the /learn/ page (and subpages of this) (so introduction moves to /learn/ and everything becomes subpages of that ...)
Let's check the skeleton again together
Make a "readable" table of contents on the /learn/ page using headings that are sentences (so it is readable)
Look at the coggle and consider moving key parts of it to a canvas ...
Skeleton
Make It Markdown does X
Markdown is a lightweight markup language used to format text
TODO: break this down + give examples
Markdown is a way to author that contrasts with with WYSIWYG editors like Word we are used to by presenting
Yet Markdown uses formatting that aims to be close to what we would expect so the raw marked up text is still human readable TODO: shorten
The markdown name comes frm the contrast to markup
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
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.
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