Aaaargh: 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 01/18/2021 at 07:181 Comment

A main idea of #Minamil is reproducibility.

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

HaD project instructions appear to allow adding steps only at the end of the sequence. No reordering or inserting mid-list. Non-starter for composing non-trivial instructions. 

(Please comment if you know what I'm not seeing.)

Update: I asked at Project about reordering instruction steps and heard back from @Cees Meijer:

There is. Just 'grab' (Click and hold) the number on the left side of the caption. Though not immediatatly obvious, if you now move up or down the whole instruction. You must move carafully, but if you arrive at a spot where it can be dropped you will see the numbers change.

to which I replied, in part:

Ah... had to go find a desk with a real old-fashioned computer on it to run a browser that shows the numbers. Even when requesting the "desktop" site, neither Chrome nor Samsung's browser show them - on a couple different Android devices/versions. ...

So - apparently I can do this in HaD with a sufficiently large and heavy browser. Hmm. Is it worth the freight?

:end update

Instructables is all about instructions and at least makes ordering/inserting steps easy. But their flakey editor makes writing anything but plain text a chore for short 'ibles so I fear to step in that pit for a longer project. I just tried some experiments to see what formatting options are safe; that turned out even worse than expected. Nope.

("Step 53" would prolly look a little discouraging anyhow, so ideally the build sequence will include some chunking.)

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

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 of handcrafted nonwysiwig composition and manual asset/link management (lots of images).

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.

"pages" at github? That's something that has mostly escaped my attention. Can start with themed markdown and handcrafted navigation, with potential for fancy static site generation from a somewhat abstracted content representation by some means that I know nothing about yet. Oh great - more project recursion.

So I started a github pages sandbox to see what that's all about. I know nothing of this Jekyll they speak of. Some sort of HTML compiler, apparently -- which means learning whatever newfangled representation of content the kids are using these days. And choosing a theme to start with. "Slate" looked ok at first glance, but then it uses half the screen for empty sidebar. So back to the options: nope; nope; nope; nope; nope;...;nope;rewind;nope;nope;nope ... ok there's some things I like about this "architect" theme, but what's with the generously allocated but mostly empty sidebar again? That would be great for a site nav tree, but no such magically appears. So wading in to figure out  enough Jekyll and Sass to make that go away -- which wasn't much but it begins another level of dreaded project recursion.

So at this point I guess I'll give this markdown-in-sidebarectomized-Jekyll-theme github pages thing a try.  .... next question: how does it handle images .... using the in-github editor? i.e. can I do this in github's editor or need the full local heavyweight git/jekyll/whatever package deal (do not want)? 

I've been drafting in a google doc, but it's time to find a home for this.  The looking is burning a lot of time.

Maybe someone already knows the answer...

Demonstrating the function of the Metaproject: a place to dump a writing rant without killing a project's SNR.


Ahron Wayne wrote 01/31/2021 at 04:59 point

The first time I published any kind of how-to it was on instructables. Advantages: A burst of attention/prizes possible, everything is on one page, you can upload a bajillion images, no problem. Disadvantages: The editor (argh! I lost my work so many times), and it's not really meant for any continuous projects, like with hackaday logs. 

Or you can host it yourself with a simple format that remains stable for 25+ years:

  Are you sure? yes | no