For example, if I want to collaborate on making a (non-computer related) textbook with someone, and we want to use git as a version control system. Should we use github/codeberg for this or is there a platform that’s more suitable for using git in nontechnical contexts?

  • queerlilhayseed@piefed.blahaj.zone
    link
    fedilink
    English
    arrow-up
    6
    ·
    4 days ago

    I haven’t found anything better than codeberg. The following novella is a reflection on my experience with a similar problem.

    I have all my poetry and short stories (and D&D snippets and board game / video game design snippets and screenplays and draft policy proposals and diatribes on the nature of being and other misc stuff that’s hard to categorize) in a single giant git repo. It works okay though I find it really hard to organize everything in a strictly hierarchical structure and I often have a hard time finding things I wrote because I can’t remember if it’s in the “boardgames” dir or the “video_games” dir, etc. I don’t think anyone but me would ever be able to use it. Not because it’s too esoteric, but because the organizational structure grew up organically over the years and makes no sense when viewed in its current form without an understanding of the history of the repo. It’s a very similar phenomenon to opening up an old code repo for the first time and being overwhelmed by the messiness of it, when someone who has been maintaining the repo for years has a built up schema of how the repo is acutally organized and can navigate it somewhat more effectively than someone new to the project

    What I’m saying is that keeping git repos organized sensibly over time is really hard, even when dealing with something as highly structured as source code, and IMO it’s much harder with more loosely-categorized creative writing snippets, if for no other reason than there’s not a strong tradition of creative writers using collaborative editing tools like VCS (though there are, I think, other good reasons why it’s harder).

    If I were to reformat my repo, I would probably start by trying to come up with a more formalized type system, a formalized metadata system, and a linking system (e.g. I would like to be able to create a link from a scene in a script to a character bio or a macguffin description). You can do links with markdown if you’re familar with it, I sometimes do that but I am pretty inconsistent with it, most of the time its too much bother to maintain them when I keep shuffling documents around (because I don’t have a well-defined type system…). Obsidian also has this feature; I haven’t been able to get myself into a natural flow writing Obsidian documents, but it’s worth checking out I think as a tool for creative writing on top of a VCS like git. If none of these sound immediately useful they can be put off until they’re needed since it’s easy to overcomplicate projects in the beginning by anticipating future problems that may never materialize, these are just things that I want for my own writing style.

    Whether or not you use something like obsidian, I think for creative collaborative projects it’s perfectly doable to use git, but it makes sense to spend some time at the top thinking about the shared rules that collaborators will need to know in order to keep all the contributors from stepping on each others’ toes. These rules should be in the repo itself in a README and should be regularly reviewed by collaborators because you will almost certainly find better ways of doing things as the project grows. These rules should cover things like:

    • How are files structured? Does every project get its own top-level dir?
    • Do projects share a common structure or does every project get to define its own structure? if the latter, should each project be a separate repo?
    • Do you have a metadata system? If so, what types of metadata do you anticipate and how should it be formatted?
    • Who gets to commit to each project? Is there a review process? The answers to these can be “anybody” and “no” but I would recommend at least thinking about it before
    • how do edits work? Are you going to commit everything to main before it goes to editorial review? or do you want to have feature branches that editors review and approve before merging to main?
    • How does the team update the rules? which collaborators can submit PRs for the rules document? what is the mechanism for making sure that the rules are being followed, at least well enough to keep the project usable?

    If you are like me, all this might sound like extreme overkill for something as simple as loosely structured creative writing. That’s because it is, until a project grows beyond a certain size, and historically I do not recognize that size boundary until I am well past it and my repo is an unmaintainable mess. It might help to discuss with your collaborators what they think the project would look like when it’s a few years and a few complete projects old: what problems will you want to solve then? Can they be anticipated in a way that doesn’t unduly burden the very difficult task of getting the whole endeavor started? A little of that can go a long way to preventing the project from losing steam because they repo just gets too unwieldy to be fun to write in.