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

    Paul McClay03/29/2021 at 20:35 0 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.   

  • Aaaargh: where to compose/host build instructions?

    Paul McClay01/18/2021 at 07:18 1 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 #Hackaday.io 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.

  • Ironic

    Paul McClay12/22/2020 at 03:43 0 comments

    Ironic to be grumbling that my mill projects are running well ahead of writing about them. It's hard to write about not making progress, but not ironic to grumble about that.