• Please review our updated Terms and Rules here

Why does building something from Github have to be in a "secret" language and needlessly archaic with no real instructions?

VERAULT

VERAULT

Veteran Member
Joined
Jan 30, 2012
Messages
8,564
Location
Connecticut, USA
I like many of you really enjoy building new devices. Sometimes you find gerbers and BOM and assemble it yourself pretty easily but other times.. And maybe more often than not you have to Assemble or Build the software... And if you had real instructions which were written in a clear concise way for the average joe it wouldnt be a problem. But for some reason alot of these folks assume you speak their lingo and can read their thoughts.

I read online someone described Github as "you ask to use a phone and someone throws you all the pieces of a dissembled phone and says 'thats a phone'.

So in a nutshell I want to try building one of these A2 Analog boards Boards: https://github.com/V2RetroComputing

Can someone who speaks the super secret language and has a happy little decoder ring tell me honestly HOW to build the software?

I mean I need a JED file to load the gal.. I know that much ... But where are the instructions?
 
Do you really have a question? Or do you just need to rant? (both are valid options, IMHO)

picopal-v1 - it has a build.bat file, so presumably all build tools needs to run under a (MS-)DOS environment
analog-preload - it has a build.sh file, so it presumably runs under a Linux / unix-like environment
analog-firmware - it has a build.sh file, so it presumably runs under a Linux / unix-like environment
analog-utilities - it has a Makefile, from the contents it seems to be using cc65, there are other comments in there to help you find other parts needed
analog-hardware - you need KiCad for this
 
I think it's likely they did not really plan to offer this to others so they knew what they were doing and how to build it or assemble it. Likely they never wrote up any instructions because of this and then someone convinced them to post it to Github. I do feel your pain though.
 
tingo said:
Do you really have a question? Or do you just need to rant? (both are valid options, IMHO)

picopal-v1 - it has a build.bat file, so presumably all build tools needs to run under a (MS-)DOS environment
analog-preload - it has a build.sh file, so it presumably runs under a Linux / unix-like environment
analog-firmware - it has a build.sh file, so it presumably runs under a Linux / unix-like environment
analog-utilities - it has a Makefile, from the contents it seems to be using cc65, there are other comments in there to help you find other parts needed
analog-hardware - you need KiCad for this
Click to expand...
I did ask a question. Yes it was a bit of a rant but my question is genuine.
 
tradde said:
I think it's likely they did not really plan to offer this to others so they knew what they were doing and how to build it or assemble it. Likely they never wrote up any instructions because of this and then someone convinced them to post it to Github. I do feel your pain though.
Click to expand...
In most cases, people publishing such projects assume that whoever wants to use/build it, has enough basic knowledge to be able to e.g. program a GAL with a JED file and all the other stuff. The knowledge you need for this is always the same, so there's no need to repeat it again and again in every project. Just like not every website offering disk images tells you again and again what a disk image is and how to use it.
 
The instructions look pretty reasonable..

github.com/V2RetroComputing/analog​

Building the project files​


Clone this repo and issue the following command to pull in the submodules

# git submodule update --init

The build.sh script in the analog-firmware project will build all the firmware variants. If you wish to build a single variant, check the build.sh script for the syntax for the build folders.
 
Most seem to dislike documenting projects, they just want to move on to the next.
Conversely, I quite enjoy it, and these docs later become essential when six months later I've completely forgotten what I did... :)

For most, Github is just a safe place to keep their work. That others can make use of items stored is by the bye, thats often not its primary purpose.
 
tradde said:
I think it's likely they did not really plan to offer this to others so they knew what they were doing and how to build it or assemble it. Likely they never wrote up any instructions because of this and then someone convinced them to post it to Github. I do feel your pain though.
Click to expand...
As I surf the mean rollers in the Internet Archive, using the period names sure helps. Another irritant is "everybody knows" so nobody described anything. So, I search for things using names that weren't in use at that time -AND- the articles that describe the process or device are scattered. If I can't explain something well enough so you can do it reasonably well, then I >DON'T< understand it well enough myself. These poorly documented projects are as good as the Cargo Cult in the Pacific, or the Boy Bands... rote repetition without mastery.

PS. If you want to play advanced blind man's bluff, search the patents from 1987-1996 for Micro Channel stuff, Lawyer-sprache in spades...

Quote "For most, Github is just a safe place to keep their work. That others can make use of items stored is by the bye, thats often not its primary purpose."

100% agree. But that's like trying to understand period situations by opening up Power Point slideshows where there are no notes. Perhaps some thought and effort should be placed into documentation while the project is fresh in the mind...
 
Last edited:
Al Kossow said:
That's what one hour EweToob videos of talking heads are for.
Click to expand...
Al, but I did try watching about 5 videos on becoming familiar with Github. Unfortunately all the ones I trudged through were about what GIT is and starting your own project. None were about understanding and navigating someone elses project, And it seems most were based around 100% software repositories not hardware. Trust me I was searching. I just didnt find any that explained it well.
 
Last edited:
mark0x01 said:
The instructions look pretty reasonable..

github.com/V2RetroComputing/analog​

Building the project files​


Clone this repo and issue the following command to pull in the submodules

# git submodule update --init

The build.sh script in the analog-firmware project will build all the firmware variants. If you wish to build a single variant, check the build.sh script for the syntax for the build folders.
Click to expand...
If it seems reasonable to you then I suppose you have done it before.

Again I tried this on windows.. Got nowhere. I loaded up a p4 laptop with lubuntu and tried it.
They say linux already has all the tools you need to do it.. Well thats a lie.. your distro MAY have the libraries but most likely you will have to add them. I had to add GIT. And even then I have no way of knowing it I have all the dependencies needed or not.

So I Cloned the repository.. Ok whats the exact command? I tried GIT CLONE WEBSITE URL
It made a folder on my laptop called analog.. but all the folders inside were empty.
I tried the # git submodule update --init
And it didnt seem to do anyting after I hit enter.

Again this isnt a complainfest. I would like to understand this better so I can build more advanced projects. Im not a software guy by any means and I dont feel any of this is reasonable or straightforward. And I can tell you its based on the continuing culture where people are getting worse at communicating. I have worked with plenty of folks who excel in their niche fields and when there is a large project they have no idea how to speak in broader terms for mass understanding.. They just use thier own inherent terminology EXPECTING people to know what they are talking about. I have been team lead and project manager on plenty of big operations and this happened frequently. I would have to cut off someone speaking with statements like "would you please explain that in terms and outsider to your field might understand..." and repeat things like that at nauseum as they didnt seem to catch on what they were doing was incorrect or learn from it.
 
Last edited:
Chuck(G) said:
I've never used git to obtain files--I just use the "Download ZIP" link.
Click to expand...
So I'm not the only person who does it that way :)
There is probably a more elegant way to "just clone the repo" ... but I have not been able to find instructions showing how to do that.
 
Am I the only one who thinks you're asking a bit much? People who present something like hardware for vintage computers (for free) on Github invest a significant amount of time and effort in developing this stuff. They have fun engineering this and share freely. Writing documentation and manuals, or even step-by-step instructions is mostly considered boring. So, to get to stuff for free, you probably need to invest a bit of your own efforts and make yourself familiar with the technology. If that exceeds your capability, this specific project even goes as far as offering ready-made hardware together with firmware (and, I believe) even documentation on Tindie.
 
Also this card uses a Raspberry Pi pico. Where are the detailed instructions on how to load that? I guess in the interim I can at least get that part done.

Maybe some folks find step by step instructions patronizing. If they are laid out well I certainly dont mind all the basic things being covered.
 
If you are on the main page of the Github project, click on the green code button and you can select Clone instead. I always do the download ZIP file myself.
 
You must log in or register to reply here.
Back
Top