Aaaargh, cont.: where to compose/host build instructions?

A project log for the Metaproject

Write about projects to get better at writing about projects.

Paul McClayPaul McClay 03/29/2021 at 20:350 Comments

tl;dr: v2.0 of current doc effort posted as an 'ible -- after ruling that out in last log :-/

Silly many hours - since the beginning of people expecting me to write in school, writing inefficiently has soaked up a huge chunk of my life. Part of why I don't get write-ups done.

Since last log whinging about where to compost/host build instructions...

Concrete specific build instructions (work in progress) will get long.

Yeh. Long like by far the most voluminous writing project I've ever actually completed a draft of. A small victory over self for me, but mainly useful to make me rethink the assembly sequence so I could flush most of it and start over.

HaD project instructions appear to allow adding steps only at the end of the sequence. 

Thought I, until kindly informed of how to re-order steps. (answer:use a desktop browser not a mobile browser requesting the "desktop site".)

But I don't see how to work on not-yet-public instructions in a public project -- vs. log entries which can be saved in draft. I could do major "instructions" drafts as separate projects, but project proliferation. A way to copy-paste instruction steps en masse would help. I could make Step 1="work in progress; don't bother".

Instructables is all about instructions and at least makes ordering/inserting steps easy. But their flakey editor [...] Nope.

And then I did v2 as an 'ible. It helped to be writing more assembly and less essay the second time around. Making peace with the editor included doing a lot of fixing borken nested lists (ul, ol) in direct HTML mode but not trying to do anything in HTML mode that the WYSIWIG editor wouldn't do. (exception: direct HTML video embed works -- at least for now). That, and they opened a "Simple Machines" contest about the time I started thinking of a re-write.

Google docs? No big obstacles, just not feeling it. ... Maybe I'm being stupid about that.

Shortly after writing the last log, I went all-in on Google docs for the first complete draft. I think the completely unstructured canvas helped with pushing bits and pieces around when I had no idea how the flow would work out.

I'l prolly use GitHub at least for versioning vector files for the laser cut parts. So maybe do the instructions in markdown files there? That's a lot [...] manual asset/link management (lots of images).

1. Duh. Already have the CAD in Onshape and Os can manage versioned assets along with the CAD just fine.

2. I tried a bunch of markdown editors and have used StackEdit before, but found none with a low-friction inline image workflow. (among Android and/or in-browser vs locally installed Windows aps)

wiki at github? Looks like I'd have do all the navigation linking -- unless finding a clever trick with categories and sorting or something.  Or ToCs on a few rilly long pages.

Why did I give up on that? No TOCs, iirc.

"pages" at github? [...] So I started a github pages sandbox [...] I guess I'll give this markdown-in-sidebarectomized-Jekyll-theme github pages thing a try.

It seemed like the expected use case is working in a local repo, which I'm avoiding by choice, and see above re online markdown editors.

The subject write-up, by the way, relates directly to #A Cheap Compact Linear Slide, and through that indirectly to #Minamil: a minimal CNC mill. And friends.