Consolidate Obsidian User Guide (and add to Tao)

[catherinet1]

DEPRECATED IN FAVOUR OF https://github.com/datopian/portaljs/issues/883

UPDATE: 2023-05-24 everything important from here and threads has been captured to https://github.com/datopian/portaljs/issues/883

We have instructions and guidelines for using Obsidian in various places. It would be good to consolidate these materials in one place -- e.g. the Tao -- for ease of reference and to avoid duplicated future effort.

Materials we already have to integrate:

• https://lifeitself.org/ecosystem/contributors-guide
• https://web3.lifeitself.org/meta/editing
• Obsidian Tutorial meeting Recording and Transcript
• Adding internal redirects on the website https://www.loom.com/share/ac3876bb390b417f9077a3e052986a44

Acceptance

• Job stories for user guide(s) (what 'How to...?' questions are wanting to be answered?)
• A consolidated guide for using Obsidian etc. (see full list of topics in comments) exists
• Consolidated user guide is added to the Tao

Tasks

• Outline key job stories for user guide (e.g. what 'how to...?' questions are needing to be answered?)
• Review existing content (see above)
• Outline purpose of consolidated guide
• Outline proposed contents of consolidated guide
• Create consolidated guide
• Add to Tao

[rufuspollock]

@catherinet1 👍 really clear and useful issue.

One thought: really we are covering a few topics here:

• Markdown
• Obsidian
• Git and Github
• (Flowershow / NextJS)
• How our website works (which combines the above)

Given how much there is there I wonder if worth orienting this around more simple howtos/job stories. And for that would be useful to here from e.g. @ZybN or @nathenf and others what kind of questions they had or still have.

[nathenf]

@catherinet1 I would be happy to include a few questions I have. I still feel I only have a basic ability to use it right now and feel like I make a lot of mistakes.

One 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.

• 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
• How to use tailwind
• How to redirect pages

[rufuspollock]

@nathenf can you "braindump" a list of things you have or had issues / questions about re editing our site, using obsidian etc

[rufuspollock]

@nathenf merged your new comment from below into here and deleted that one to keep things clearer.

[catherinet1]

@catherinet1 I would be happy to include a few questions I have. I still feel I only have a basic ability to use it right now and feel like I make a lot of mistakes.

One 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.

@nathenf Sure, I imagine it would be helpful to capture the questions you have. I created a section at the bottom of the issue body where you (and anyone else) can add job stories or how-to questions; please feel free to populate it

[rufuspollock]

@nathenf Sure, I imagine it would be helpful to capture the questions you have. I created a section at the bottom of the issue body where you (and anyone else) can add job stories or how-to questions; please feel free to populate it

I wonder if we create a discussion in forum here and keep issue focused on actual tasks. We could have a task which is "collect FAQs and common needs" which we open a discussion for and which people can post and upvote etc in.

We could even use the body of that discussion to draft the outline of the doc (i think we can all edit the body of discussions) and then post that over to the tao when it's reached a decent state.

[rufuspollock]

@ZybN can you also list any stuff you've encountered with obsidian, git, github etc etc.

[ZybN]

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.

[rufuspollock]

@ZybN excellent - thank-you. Can you link the video?

[ZybN]

Here is the link to the video that explains the Github and Obsidian workflow

@nathenf can give access to view this video in case it doesn't open.

[rufuspollock]

Rufus' list of things to cover 🚧

• 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?

[nathenf]

@Liyubov and @msantolini this is the discussion to list any struggles you are having with the website system!

[msantolini]

thanks 🙏

[msantolini]

Thanks - I can’t have access because I don’t have a lifeitself.org <http://lifeitself.org/> email address. Could it be publicly available? Thanks!

…

On 5 Apr 2023, at 08:11, ZybN ***@***.***> wrote: Here is the link to the video that explains the Github and Obsidian workflow <https://drive.google.com/file/d/1Ow0RYya8e3JMZhY5cpCYspsZAA1loses/view?usp=sharing> — Reply to this email directly, view it on GitHub <#393 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAHJRNNEIGDDVQ6NPF77NMTW7UEJ5ANCNFSM6AAAAAAWLNBBVA>. You are receiving this because you were mentioned.

[rufuspollock]

@msantolini are you asking about the recording? I don't have access either and not to do with having lifeitself address - the owner has to share with the world for them to become accessible /cc @nathenf

[rufuspollock]

@nathenf could you take on getting a consolidate list of howto needs into the main description section and maybe some kind of ranking to indicate priorities.

[olayway]

@ZybN I've created a basic skeleton of the guide here: https://docs.google.com/document/d/1hyiaZlbzXJKx1eoCywsBpn1Xs1giOrlL_QzSAUFczDk/edit#heading=h.aqkggy987oqg

Let's first agree on the list of topics (table of contents) before we start writing actual content.

cc: @nathenf, @catherinet1, @rufuspollock please also take a look and comment :)

[catherinet1]

Thanks for the thought you've put into this, Ola! Looking good. One thought I have is I wonder how in the contents page we can make it easy for people to find the information they need. Especially non-technical contributors, who are unfamiliar with terms like committing changes, pushing, pulling etc. Can we have headings of job stories which are in the language that a non-technical person might come with? e.g. "Editing a single website page" (instead of "Small changes to single documents"), "Adding a new page", "Editing multiple website pages at once" etc. ? Does that make sense? Wondering what the most intuitive language would be for a non-technical contributor to find the information they're looking for.

And I quite like the notes from the section "2023-05-10 sketches" at the bottom of the issue re whether people are how people (just want to follow step by step instructions for getting the action they want to do done) vs. why people (want to understand why they're doing what they're doing) -- so maybe in a box/section we could have an explanation/translation between the non-technical language and the technical language.

[olayway]

Thank you for your input, Catherine! I totally agree with you and I'll make sure the headings are written in a way a non-technical person can understand. I also like the idea with boxes with translations/explanations. I'll give it a go!

As for the scope, is there anything I missed? Anything you'd like to find information about that's not yet included?

[rufuspollock]

DUPLICATE / MOVED. Consolidating discussion on https://github.com/datopian/portaljs/issues/883