codexfelis / oratio Goto Github PK

Article type

This is a conceptual article (what is...)

The title should be something like: What is AI?

Target audience

Humanistic researchers who've heard of Chat GPT, LLMs, deep learning, machine learning etc but don't understand the differences and difficulties.

What do people reading this article already need to know about, what background knowledge do they need, in terms of technical or domain concepts?
Nothing - the article will explain classical computing, symbolic AI, machine learning, deep learning, neural nets etc in high level terms.

What problem is the person reading this trying to solve in their research? Try to think of a concrete example situation why someone would need to know about/how to do this thing

They need to know what AI "is" and what it isn't; how fancy stats can be useful, and the challenges it poses in terms of training.

Things to cover

How do simple programs work?

Symbolic AI and Machine Learning / neural nets / supervised, unsupervised, reinforcement learning / different architectures / what's an LLM? What's generative AI? / Ethics

Is it related to anything else we've written about?

If you can, point to things we've written about (or are planning) that are useful as prerequisites for this article, or as follow-up.

Anything else?

Anything else we should know? Do you have links to anywhere on social media/blogs of people asking about this topic? Do you have links to relevant/further reading?

Next steps

Would you prefer:

• I want to write the article mostly myself

In either case, the next step is to wait for Dan or Caro to read the proposal and check it's something we want to include, then we'll take a branch and start working on an outline together. Thanks for your contribution 🎉

While its mostly us two writing, maybe isn't so relevant (but maybe it is?), but if we get external contributors authoring it might be nice to credit them clearly. Not sure what's the best way to do this if it is useful - name with link to website/preferred social media is maybe sufficient, or would we want full-on author bio pages?

We’ve decided to adopt sembr, so we need to change guidelines for contributions.

Article type

This is a conceptual article (what is...)

The title should be something like: What is Python and why should I use it?

Target audience

What do people reading this article already need to know about, what background knowledge do they need, in terms of technical or domain concepts?

They should be familiar with basic computer concepts and programs. No specific knowledge beyond knowing why people use excel, for example.

What problem is the person reading this trying to solve in their research? Try to think of a concrete example situation why someone would need to know about/how to do this thing

They've seen a few presentations about digital methods, they've heard of some cool projects. They want to know whether digital methods have some sort of use case in their own research, but know nothing about programming or even where to begin.

Things to cover

What points does this article need to touch on? Are there a series of steps to outline? Write them here
What's Python?
What's a programming language? What's a program?
Ok but why is Python popular?
What can it do?

Is it related to anything else we've written about?

If you can, point to things we've written about (or are planning) that are useful as prerequisites for this article, or as follow-up.

Anything else?

Anything else we should know? Do you have links to anywhere on social media/blogs of people asking about this topic? Do you have links to relevant/further reading?

Next steps

Would you prefer:

• [ X] I want to write the article mostly myself
• I would like you to write about this for me

In either case, the next step is to wait for Dan or Caro to read the proposal and check it's something we want to include, then we'll take a branch and start working on an outline together. Thanks for your contribution 🎉

https://citation-file-format.github.io/ - is this even relevant to mostly-content? is there an alternative way to make it easy to cite the website/particular articles?

SemBr (Semantic Line Breaks) is (for our purposes) a way of formatting text in markdown such that meaningful clauses are on separate lines in the source text file. This doesn't affect how the text is rendered.

I like it because it makes editing via pull requests easier, as you can target very specific bits of text for comments. Also makes git diffs very clean. It can help with writing flow (helps me write more, shorter, more coherent sentences rather than word vomit).

But it does also look weird and unfamiliar to the writer when looking at the plaintext, and can make writing a little slower.

Is this something we want to adopt? Are the upsides for editing enough to balance out the weirdness of writing?

If so, we should add something to CONTRIBUTING.md. If not, I should reformat the github article, and we need a process or convention for line-editing each other's writing that works at the paragraph level

Article type

This is a conceptual article

The title should be something like: What is a code formatter (and why should I use one?)

Target audience

People who know even a tiny bit of some programming language (probably python or javascript?), particularly if they are working on code with multiple people. They probably need to know what indentation means

This probably isn't a thing humanities programmers would think to look up, or need to know about unless they run across some code that is using them, but in my mind falls under the set of tools (like linters, task runners, good autocomplete, configuring your IDE) that would make programming easier if you knew they existed/were possible.

Things to cover

• what's a formatter - something that reformats your code, does things like fix indentation, line breaks, consistent quote styles
• some names of formatters, and links to them - black, ruff (or less commonly yapf or autopep8) for python, prettier for javascript (but also HTML and markdown?) (are there ones for R? I don't know the ecosystem at all)
• some (black) have basically no things you can configure, so all code formatted with black looks basically the same. some (prettier) have a million configuration options, but there's some common config files you can start from
• what does having a formatter make easier?
  • lays things out nicely for you without having to do things by hand, which can make code easier to read - show an example of badly formatted JS vs what prettier does
  • makes all code you write look the same, so it's less hard to switch between files/projects (would be good to find a study to back this up?)
  • if you're working in a team, having a shared formatter setup means you don't waste time discussing/arguing about formatting

Is it related to anything else we've written about?

Linters. General IDE setup stuff. Should probably also write a concrete article about how to add black/ruff to your python project

Anything else?

nope?

Next steps

I'll write this. @danwaterfield do you think this is a useful set of topics to cover in fairly short articles? Its things that I've always picked up from other people's code or watching them work, which I guess people programming in the humanities don't really get to do often, but makes a real difference to workflows and code quality

Article type

This is a conceptual article (what is...) Knowledge management

The title should be something like: What is knowledge management and how should I use it?

Target audience

Very little knowledge assumed; maybe they'll have heard of "second brains" or notion/obsidian. They'll have heard about good research practices, and they'll either be embarking on postgrad or in writing up mode or figuring out how to deal with archival research.

They'll have a massive amount of material and panicking about how to get it all organised, or remembering where everything is.

Things to cover

What's knowledge management; different approaches; different ontologies; notion vs obsidian; what if you're halfway through a career etc.

Is it related to anything else we've written about?

Not yet

Anything else?

Anything else we should know? Do you have links to anywhere on social media/blogs of people asking about this topic? Do you have links to relevant/further reading?

Next steps

Would you prefer:

• I want to write the article mostly myself
• I would like you to write about this for me

In either case, the next step is to wait for Dan or Caro to read the proposal and check it's something we want to include, then we'll take a branch and start working on an outline together. Thanks for your contribution 🎉

There's a few sets of related topics that came up in article ideas - AI, git/hub, setting up your coding environment. It might be nice to link these together into some sort of more structured read this, then this, then this and you'll be able to do X and Y?

Sort of like a curriculum but less formal. The word that came to mind was "learning path" but I'm not sure I like it. Just as a way to provide an entrypoint to a topic, rather than make people go jumping around or searching if they didn't arrive here in search of something very specific?

Example (with a bunch of imagined articles) for a path to being confident interacting with other people's code on github:

• Intro to the path: you know nothing about version control, but are either curious or need to use it with a team or an open source project for work. We assume you know nothing at the start. At the end, you'll be able to use git for your own stuff, and with a team via github. Go read these things in this order
  • what's version control and why do i care
  • what's git
  • what's github
  • how to git alone
  • how to write a good issue?
  • how to PR
• Yay, now you know how to git. Go make a PR somewhere (maybe here!). Here's some additional resources from other places if you want to learn more (annotated list)

@danwaterfield do you think that would be a useful thing? Where would they live? Probably a first section in the sidebar? What should we call them?

Sorry for word vomit, insufficiently caffeinated but idea needed to come out before I forget it.

Article type

This is a concrete article (how do I...)

The title should be something like: How do I make a pull request on GitHub

Target audience

Someone who knows just enough about git (see #2) to make commits and stuff, and knows what GitHub is (#4 ). Nothing specific about code.

The target user is trying to contribute to some repository they don't own in a small way. Take the example of fixing a typo in some docs? (the idea that this article is required came up while helping historians contribute to some markdown documentation)

Things to cover

• what even is a pull request? (don't think this is enough to need a whole separate article?) Note this is a hosting platform thing, not a core git thing

• the steps are the same on most other code hosting platforms, just the UI might look a bit different. GitLab calls these things Merge Requests, but it's the same concept.

• this process is very dependent on what maintainers want for their project! Read their docs/readme/contributing guide first, and do what they say not what we do!

• in the absence of conflicting requests from the maintainers of the thing you want to contribute, here's a process I like:

• code on a team you're part of (don't need to fork)

  • tell people you're gonna do the thing!
  • clone code
  • take branch
  • make change
  • make commit (with a good message!)
  • push your branch
  • make sure builds are green etc
  • open a PR
  • get feedback
  • do more commits
  • get approved
  • merge PR
  • success!

• code not on your team (Do need to fork)

  • fork the repo
  • do the rest of the things (don't forget to branch!)

• how to write a good PR description (and good commit messages along the way)

• general tips like don't make your PR too big, ask the relevant person for review

• what's builds and why do i care if they are green (very vaguely, just enough to say that the build things are there for a reason, and you should make them green, ideally before making PR)

Is it related to anything else we've written about?

Articles #4 (published) and #2

Anything else?

There's a blog post somewhere explaining why not to ask to merge from main on your fork, I'll find it

https://intro.opensauced.pizza/#/ is a good resource if people want to do more open source stuff, but not from an academic perspective

Next steps

Would you prefer:

I want to write the article mostly myself

@danwaterfield did I forget anything in the outline?

https://github.com/codexfelis/oratio/blob/main/src/content/docs/what-is/github.md This initial outline.

This is for people who know nothing really about code, git or other version control systems.

It should link out to another article about what is version control (issue coming soon) for more context, and possibly one about what is open source software?

The initial outline was

• summary what/where is github
• Why should I care?
  • Finding other people's code
  • Using issues for feedback
  • Sharing my own code, writing or data
• Are there alternatives? eg gitlab, bitbucket (full featured, but less community/visibility), codeberg (mostly just the code side)

@danwaterfield anything else should go in the outline before I start drafting?

I initially pushed this in a bit of a hurry, and forgot to update the readme!

@danwaterfield I guess we can license this content as some kind of creative commons, maybe CC BY-SA?

• add license
• add repo description and tags
• configure funding.yml
• add code of conduct
• update the readme
• deploy on a real domain name

Article type

This is a concrete article (how do I...)

The title should be something like: How do I deal with merge conflicts in git

Target audience

People know just enough git to be dangerous, and are working with some kind of remote (GitHub probably). This probably means working with other people, but could also be you using git to sync between >1 computer

When you try and pull/push and someone else has made changes, and git just gives you confusion.

Things to cover

• quick reminder that you should know what git/hub are, and what pulling/pushing means conceptually
• outline scenario - your colleague made commits, and you did too, on the same branch. Your colleague pushed before you did, now you're stuck
• what is git telling you?
• what are your options
  • didn't commit yet? stash pull apply
  • did commit - rebase
  • did commit - merge
  • when to pick which? this might be a team convention
• what happens when things go wrong?

Is it related to anything else we've written about?

Pretty much everything about git and github.

Anything else?

Definitely should link to Julia Evans on git - oh shit git, or her newer articles
(I just went looking for links and https://jvns.ca/blog/2024/02/01/dealing-with-diverged-git-branches/ is pretty much exactly this topic, with fantastic words as expected)

Next steps

I want to write the article mostly myself

Example situation: you have a small data set or writing project in a text/CSV/markdown file that you work on over time, and want to track changes and have a remote backup (relatedly, we probably need a what is version control)

Things to cover

• we assume you know why you want/need to use version control

• we assume you know how to get to your terminal/command prompt and run commands

• we assume you're working on a single computer (so you can't get merge conflicts)

• we won't cover branching/merging/pull requests here

• install git, make a github account

• create a repo on github (private), explain the instructions they give when you make a repo

• add your file, make a commit with a message

• push your commit to the remote

• make more changes, commit and push again

• view history/file at older versions in github, view diff of what you just did

• if your computer is toast, recover onto a new machine by clone the work you did from github