Close

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:352 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.   

Discussions

Inne wrote 05/25/2021 at 12:53 point

Hi Paul, I read this and enjoyed it. Keep writhing about your journey about writhing, documenting and promoting things. It is something I am wondering myself, for instance what to write in project logs. Should I be concise with clinical presentation of how to build it or tell how this project came about and what the philosophy/goal is behind it. For whom am I writhing this anyway and why. All in all, know that someone is reading your things and enjoying them. Have a nice Tuesday.

  Are you sure? yes | no

Paul McClay wrote 07/02/2021 at 07:19 point

(a month later...) Thanks Inne for the feedback! There will be more to say about the writing I'm sure...

For whom and why are indeed key questions. Sometimes I have to write the meandering long story in order to work out the concise version -- and sometimes abandon the long form because it's then served its purpose -- which can be a horribly inefficient process. I'll suggest that putting the concise part up front/top and marking a clear end of it (or link to next concise part) can buy license to add arbitrarily much philosophical contemplation and storytelling after/between for the person who might someday care to read it.

  Are you sure? yes | no