Site Navigation

Home
Search
All Pages
What's New

Key Pages

Meetings

Markdown and Git for Collaborative Writing, 2023-08-17

Call Details

Note: You can save this document at any point to your computer. Click the three-dot menu at the top right, and select Download > Markdown.

Ideas for Next Meeting(s)

  • Obsidian demo / walkthrough
  • Interactive practice session
    • Markdown editing
    • Git sharing / versioning
    • GitHub-style collaboration
  • Write a wikibook on Lionsberg Wiki
    • publish an ebook
    • This would allow a group to build upon what has already been done, connect into previous topics, define new topics, and write together in already populated and aligned "substrate" for the reef that wants to form.
  • How to: develop a presentation using markdown slides, collaboratively

Date and Time for Next Meeting

  • How about same time next Thursday, 8/24?

Topics

  • Possibilities and potentials of Markdown, Git, and GitHub
  • Where to after this session?

Git Terminology

  • push
    • to the cloud - which is connected to your collaborators
  • pull
    • Pull Request
    • from the cloud - which is connected to your collaborators
  • commit
  • merge
    • Git looks line by line, can magically tell what is missing in each, and add it to the result.
    • merge "conflicts"
      • If two conflicting lines, Git will fix all it can, and flag the conflicts for the humans to resolve
      • Usually we try to develop coordination processes to minimize the number of times this happens
  • clone
  • repository
  • fork
    • Big F fork - leadership issues, disagreements, community splits into two - the orthodox and the heretics...
      • often kills a community
      • a lot of pressure to not do that
    • little f fork
      • Github uses that language to say - I want to take all your code, copy it, make changes...
      • then can make pull request - and fork merges back
      • usually a temporary copy of the whole, changing it so it is cohesive in itself, putting it back together.

Licensing and Publishing

Massive Wiki

  • markdown shared version files
  • links

Session Notes

volunteers can take session notes in this section of the page, or feel free to also create another section

  • Goal - get oriented to what we could do.
  • Then - we will decide how to proceed.
    • Mailing list
    • Chat system (Mattermost)
    • App.Podia Forum
  • Sotware developers use text and Git to successfully collaborate at high speed.
    • That can be true for writers too.
    • Using the tools proved by software developers can unlock hidden Potential.
  • WYSIWYG
    • if editing text, most people know about things like MS Word, Apple Pages, or Google Docs.
    • When you are editing text, looks like just when you print it.
    • When you want to make a change, you see exactly what you will get.
  • Markup Language
    • There is a different paradigm, where instead of having the way it looks present as you are editing, you can abstract the way it looks into instructions to the computer.
    • HackMD
    • Obsidian
    • Etc.
    • cant see it looking fancy until you push the button and computer renders it. HackMD also renders in real time.
  • Markdown
    • italic preferred (italic also works)
    • bold prefered (bold also works)
    • bold & italics? Yes, works
    • also works? Yes
    • dash space = bullet
    • computer will auto fix numbers, i.e. you can use 1. for each numbered bullet in a series.

    • header one

    • header two

    • header three

    • header four

  • Markdown Resources
    • Search for markdown cheat sheet
    • Daring Fireball - blog of guy who invented markdown
    • CommonMark - cleanup spec for markdown
    • Github-Flavored Markdown

Git

  • a distributed version control apparatus
  • created by the guy behind Linux for people to work on Linux kernel - collaboration around the world
  • a Git Forge is a central switching center everyone goes through.
  • An example of this is Github
    • a centralizer
    • files can also be swapped peer to peer
    • centralizer also creates a community of people you can cooperate with.
  • Maybe
    • what happened for global software collaboration
    • can maybe also happen for text collaboration
  • See heading above for Git Terms
  • Resources
    • Git conceptual diagram by Pete and Bill
    • ProGit - cannonical ebook

GitHub Flow

https://docs.github.com/en/get-started/quickstart/github-flow

  • simple & straightforward branching strategy
  • probably best choice to start

Git-Flow - a successful Git branching model

https://nvie.com/posts/a-successful-git-branching-model/

  • Has great set of diagrams
  • Uses "Branches"
  • We can borrow conceptual chunks to make small versions that are as complex as we need
  • Master - original term, now often called "Main"
    • If I want to do work - copy or clone Main branch over to develop branch...
    • Make edits...
    • and at some point, edits moved over to testing branch, and then eventually committed back into the main.

Github - a centralized Git Forge

  • Was an amazing boon to humanity
  • Ended up being a society wide thing
  • And then Microsoft bought it
    • Microsoft has been cherrypicking parts of the OS ecosystem, acquiring them, and improving them in interesting ways... providing more capability - and people get hyponitized into using Microsoft version of Open Source
    • Microsoft embracing and bending Open Source to their direction...
    • MS takeover of Github is kind of like Elon takeover of Twitter - changes it out of community commons.
  • Line by line, can comment on changes, ask questions, etc.
    • that ends up being in a threaded discussion around all the files...
    • Can bounce parts of pull request out and save for later
    • Can merge parts together,
    • etc.

Codeberg

  • Potentially best current Github replacement

HackMD

  • character by character real time merging, vs. git line by line...
    • as opposed to batching and committing.
  • Someday -
    • we will have real time character by character, plus phased line by line approach, working together.

Tools

  • Fill in later

The Dragons

  • what are the dragons we need to identify, and work together to avoid getting eaten thereby.
    • Microsoft

Questions, Comments

Next time can we have a demo for how to use Obsidian.md and the git plugin for collaborative writing?

add questions and comments below

There are at least five primary (effective) collaborative writing styles which can be mixed together and also developed on:

  • Single Primary Writer: One person writes, everyone else plays other roles (support, editing, research, graphic design etc.)
  • Partition Writing: Each author works on a separate part, subject to editing by others or by a common facilitator. May be parallel (Parallel Partitioning) or consecutive (Linear Partitioning)
  • Joint Writing: Authors work together synchronously and asynchronously in close collaboration on every part.
  • Scribe: One person writes based on group discussions, conclusions, and notes.
  • Hybrid: A blend of methods above or the partitioning of the document into sections written in one of the methods noted above. For example, the writing of the introduction and discussion sections using a Joint Writing method, but the rest of the work being written using the Partition Writing method. If no method has been chosen, pitch one to the facilitator of the team — while some groups get lucky and fall into success, picking a method can circumvent a variety of conflicts during the work. See further reading for more information on team writing approach classifications.

https://zenodo.org/record/4633921 (WLA: great resource)

Chat

charles charles says:(what's "ai" ...) charles says: https://docs.github.com/en/get-started/quickstart/git-cheatsheet

charles says:"improving" charles says:one would assume everything on github is scraped for openai ...?? 7:47 Bill Bill says:another git notion to add is "fork" 7:50 kHyal kHyal says:TY for the invite, Ray! TY, Peter! Loved this, have another call now. (I helped 2 type houses convert to WYSIWYG workflows in the 80s, and then helped set-up and run a Mac-based typesetting business so I appreciate your background.) 7:53 Shimon Shimon says:Interested in moving forward with collaborative project that more clearly define goals. 8:00 Bill Bill says:i need to leave; looking forward to collaborative writing practice 8:06 charles charles says:gonna jump ....thx pete & all i'm not around next week but generally interested 8:08 Butler Butler says:Ty! Peter & everyone else, looking forward the next meeting. 8:10 Ray Schmitz Ray Schmitz says:Love your idea, Jordan!

Sandbox

Massive Wiki

asdf sdf

Pages that link to this page