🗄️ "Catalogs of Stuff" Docu-thon: or How to build markdown-based sites using Flowershow / PortalJS

[rufuspollock]

Docu-thon on howto build markdown-based sites using our standard open stack i.e. Flowershow/PortalJS (and MarkdownDB)

Primary Epic this relates to: https://github.com/datopian/portaljs/issues/883

UPDATE 2023-06-16 - Docu-thon complete

What happened?

• A website for our howtos and tutorials, with some basic ones written and available https://guide.portaljs.org/
• A plan for our howtos and tutorials that we plan to write
• Clearer idea of what the audience is and thus, what the needs are

Compared to what we envisioned

A non-dev editor/author at Life Itself or anywhere else has a single online place to start that has or links to sufficient docs to autonomously (i.e. without dev support) ...

• Edit lifeitself.org
  • Create a new blog post
  • Create a new page A howto on adding a simple md page: https://guide.portaljs.org/guides/add-a-simple-md-page
  • Edit a blog post or page A how to on editing a single md page https://guide.portaljs.org/guides/edit-text-on-a-single-md-page
• Create, share and publish a micro-catalog
  • Create locally Tutorial on creating a catalog of anything in Obsidian https://guide.portaljs.org/tutorials/create-a-simple-catalog-of-anything
  • Share with others (privately) 🚧 Draft of a howto on pushing an Obsidian vault to GitHub
  • Publish
• Create a digital knowledge garden i.e. content + catalogs etc

🏆 Trophies (extras)

• 🏆 MarkdownDB has a proper website with landing page ✅2023-06-16 ❌ we didn't get to this
• 🏆 Flowershow repo consolidated as template etc ~0.5d??
  • remark plugins: marke sure stuff works

Day 1

Game for the day and what did we ship 🚢

• Finish the tutorial @olarubaj
• Have a site up and running first version of the markdownbased.org (or sth) website with the above tutorial published @khalil
• Ola could finish working on the Flowershow packages -> Portal.JS refactoring/migration @olarubaj

Day 2

Game for the day

• Flowershow refactor finalized @olarubaj
• First tutorial copy finalized @olarubaj
• Website for our tutorials up and running @khalil
• (TBC) tweet about our Docu-thon @lauren

What did we ship summary 🚢

• the website for our tutorials/howtos is up and running! https://guide.portaljs.org
• we have a graph of potential howto guides that should come next
• packages that have been moved to portaljs monorepo are building and automatically publishing to npm!
• Lauren has also refactored our tutorial/howto mix to be a real howto guide (not checked it yet though)

Day 3 Plan

What's the priority job story and persona?

Someone non-technical ...

Game for the day

• prepare a clear list of next HowTo guides we want to ship so that people can start writing
• what are the priority howtos/tutorials related to creating catalogs of stuff @catherine

---

---

Plan for the Sprint

🗄️ "Catalogs of Stuff" Docu-thon

Editor Guide for building markdown-based sites using MarkdownDB, Flowershow and PortalJS

June 2023

💐 ✍️ 🌀

graph TD

start["👋 Welcome - thanks for joining"]
brief["💼 Read the brief for the sprint"]
write["✍️ Contribute howtos to our amazing Guide!"]

start --> brief --> write

Loading

Brief for the sprint

A non-dev editor/author at Life Itself or anywhere else has a single online place to start that has or links 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

🏆 Trophies (extras)

• 🏆 MarkdownDB has a proper website with landing page
• 🏆 Flowershow repo consolidated as template etc ~0.5d??
  • remark plugins: marke sure stuff works

Read the epic for editor guide for more context

https://github.com/datopian/portaljs/issues/883

Create a tutorial or howto

• First, read this one we have created https://hackmd.io/qAJFi0O0Q9G4ZubeSCet9g?both
  • 🏆 suggest improvements
• You're going to write one yourself
  • Read below instructions/recommendations on how to create one
  • Pick a tutorial or howto to create from the list below

🏆 = bonus item

Instructions / recommendations on writing tutorials and howtos

See
#929

A tutorial is what you decide a beginner needs to know.

A how-to guide is an answer to a question that only a user with some experience could even formulate.

List of howtos and tutorials

---

---

Appendix: Brainstorm re outcomes

• We have an editor/author guide for building markdown-based sites using the F/POG stack and approach
  • Document the patter for GOMStack = git + obsdian + markdown (GODStack = Git + Obsidian + Data stack 🤣 ) (inspiration from JAMStack). Even GOJAMStack = git + obsidian + javascript + api + markdown ...
  • ?? have a new markdown guide website
• We have consolidated our existing docs for appropriately
  • Answer questions like: should i document this feature on flowershow.app or portaljs.org or ...
  • Where should we put this guide
• 🏆 Announce markdowndb on hacker news