Forth: Tell The World
So, you have discovered Forth and now you want to tell the world about your discovery ?
Note
Firstly, I don’t claim to know the best way to do this, I only know the way I approached this task when I started this website and that’s the tale I’ll tell you here.
About Me
I’m a electronics technician, not a programmer. I came from Machine Code, Assembly Code and C in embedded and started with the National PACE CPU in 1976. Before that I did industrial electronics, analog electronics, RF, PSU’s, automotive and instrumentation. I use a lathe and milling machine, I make my own enclosures and pcb’s, I have a lot of SMT and thruhole experience in industry.
I started learning electronics about 1963, some fifty eight years ago and I’ve been privileged to see and experience many of the awesome advances in electronics since then.
My Forth Journey
In 1976 the Forth addiction displayed by some Rockwell 65F11 Forth programmers was infectious and I couldn’t get it out of my head. This kept me trying Forth every five years or so but it just didn’t click for me, I couldn’t see what the fuss was all about and I stayed with C but still I couldn’t quite let go of Forth.
By 2011, C for embedded had reached the dizzy heights of FLOSS software, ARM-NONE-EABI-* for ARM and others provided a complete tool set including on chip debuggers with GDB. This environment was what I used to dream about when similar facilities cost tens of thousands of dollars, and it is a serious competitor to Forth right now.
In fact, I believe it leaves old Forths with 115200 baud terminals and end of line delays for dead in the development stage, which is why I’ve been working on more specialist Forth Toolsets for STM32.
Finally in 2014 I made up a Forth system (Mecrisp-Stellaris) to play around with it, it still took a couple of years before the Forth ‘lightbulb’ clicked on in my head, you know how it is I imagine?
And so in time I too became addicted to Forth (just like those programmers back in 1986). My addiction for building Forth devices and tools began to grow and my enthusiasm for C (on embedded) began to wane.
This Forth Site
In 2014 I was an utter Forth newbie and my learning pace was very slow. I started reading the usual books and documenting my progress and testing Forths and hardware for myself.
This site consists of all the notes I made as I learnt Forth, I just transferred them to Sourceforge one day, and update them with the Unix rsync program still.
In 2017 I added the Whats New? section which serves as the latest update index.
Where are the Modern Forth Websites?
As a new Forth user I wanted to read all I could about Forth. I wanted to read about the experiences, thoughts, trials and tribulations and projects of Forth users … but I quickly discovered almost all the Forth information on the Internet was years OLD and featured CPU’s like the 6502 and the 8 bit AVR etc.
Soon I had read and reread all the modern Forth websites I could find, there weren’t many and they were not constantly updated with new material. What was worse, many Forth sites had just stopped updating and gone cold.
Sure, there was a TON of C/Arduino code and projects online, much of it just re-pasted and rehashed, most of it lacking important information, but Forth content was virtually non-existent and it still is in 2021!
I think it was about this time I put my notes online as “The Unofficial Mecrisp-Stellaris Documentation” because I reasoned that given the absolute lack of Forth websites meant that even my poor efforts would provide some modern content for anyone as desperate as I was.
Reaching Your Audience ?
Who is your audience, how to reach them ?
Classification
I think there are two different types of Forth people and they have different needs to address.
Users
I’m a Forth user, I use someone else’s Forth, namely Mecrisp-Stellaris to make hardware projects. I have a IRC site, #forth-hardware-projects on https://hackint.org.
I don’t create Forths, I don’t know how, and I’m not really interested. I’m an electronics tech, I make hardware. Not being a programmer, I don’t mind creating documentation.
What I need, is a reliable, well documented Forth with lots of tools to aid the creation and testing of my hardware projects. I also really enjoy reading about other Forth hardware projects.
Implementors
Some people make Forths, they are always programmers, and rarely have any hardware or documentation experience. Matthias Koch the creator of Mecrisp is a bit of a rarity as his hardware skills are also very good.
A lot of programmers have played with creating a Forth and testing new concepts. Websites like Github contain many of their efforts which don’t work well, are buggy or abandoned. They do this because Forth is the easiest complete system to build and so it is a natural for this type of thing.
Implimentors seem to be always building different Forths, they never seem to actually use them in practical devices.
However some programmers build outstanding Forths and Open Source them, and users like myself get to reap the benefit of their work. Without Forth Implementors we wouldn’t have any FLOSS Forths to use!
There is TONS of Forth implementor information on the Internet as the basics of Forth don’t really change. They have #forth on IRC, and Comp.Lang.Forth on Usenet to argue strategies and algorithms for their designs.
Forth Implimentors are always flat out adding features and debugging, plus they know that their documentation skills suck so if you plan to start a documentation site about using their Forth, they will probably love to hear from you.
However don’t always assume they will have your level of enthusiasm for your documentation and remember it’s your documentation so you get final editing say.
Obviously it’s best to work together and agree on the content, but try not to bother them, remember they are very busy with their Forth, have a job to hold down, a family and shit happens to them as well!
So my advice is try and solve your Forth problems using all your energy and other resources, cry for help to the author when you have absolutely no other resources left and never assume the Forth author is waiting for your emails or doc site additions just because you happen to be writing doc about their Forth.
Architecture ?
I think Forths exist for every type of MCU and CPU ever made. This site caters for STM32 MCU’s (mainly Cortex-M0) because that’s what I use. I don’t write about other ARM based MCU’s such as NXP, AVR, etc because I don’t use them.
So at this time of writing (2021) there are unlimited opportunities for Forth sites similar to mine, but for different architectures makes and models of MCU.
Medium ?
IRC
IRC is great for real time communication but not any use for large articles, pictures and sample code etc.
Forums
Forums are great and I read a lot of them, but they don’t always handle Forth source code, schematics, flowcharts etc. Plus if the Forum goes down, is abandoned or you are blocked, so much for all your input.
If you have a lot to say, and a lot of projects, I think your own website is a better way as it’s easier to track your work and you can include all the information required.
Websites
This website is built using py.sphinx which is the official Python documentation system, but it can be used for anything.
Py.sphinx compiles a simple in-text formatting language and can output a choice of formats such as HTML, which can then be uploaded to a website with RSYNC and is ready to read.
Because Mecrisp-Stellaris, my doc, and my projects are all licensed under a FLOSS license, I publish for free on Sourceforge. Thank you Sourceforge!
Prior to Sourceforge I used a Digital Ocean ‘Droplet’ but that $5 USD a month (plus GST Tax in Australia) adds up over the years and if you’re retired and on a fixed income it soon adds up.
Note
If you do a website and use something like py.sphinx, do it at home privately on your PC for a few months before you commit it to a website, because once your website is known, it’s very hard to change the name etc.
Replying to Emails
Your readers will need your email address.
If anyone needs to respond to emails quickly it will be you, to your readers. Be advised that there are a few Forth haters about so make sure that they don’t upset you causing you to reply in a manner you will later regret. Never reply immediately to such emails, wait a few days until you have cooled down.
If they are persistent, just ignore them because that’s the only thing that online Trolls really hate. Being ignored.
Some of your readers will email you thanking you and asking you to keep writing because they love your content. They will outnumber the inevitable Trolls.
Website Name?
You’re reading “The Unofficial Mecrisp-Stellaris Documentation”, but I don’t see similar sites for Paralax Pi or P2, PIC, 8051, NXP and so on, so the opportunities are still there :)
Make sure it’s a memorable and unique name so people can find it, and don’t use common words or their searches will be lost in the millions of hits.
Content
New Forth content will be greatly appreciated by Forth addicts as we have so little to read !
Keep it updated regularly with new projects or articles, they don’t have to be world shattering and use clear descriptive non click-baity names.
A project with lots of pics (small sizes for those with modems and slow internet connections) and backstory will be loved by people like me who live to build devices.
Don’t worry about less than perfect code or errors, we all know you’ll do your best at the time and as Peter Jakacki the author of Tachyon Forth https://sourceforge.net/projects/tachyon-forth/ said in https://sourceforge.net/p/mecrisp/discussion/general/thread/f9808a64bd/?limit=25&page=1#1ca8
Code will never ever be perfect but if you did have perfect code then no one else would ever show their less than perfect code. When you share your “hobbyist” code it encourages others especially those at the same level. There are many levels and some go sideways too. When you do share, it causes you to look at your code in a different light and you see things that can be improved and made clearer etc.
Types of Content
How do you intend to reach those for whom your documentation is intended ? Examples of documentation types you may need to include :-
Here are some suggestions from my site. Remember a new Forth user trying to find example Forth code for your MCU of choice will probably find nothing, so you are in the ideal position to help :)
Dictionary tables with correct syntax and examples
glossary:
Table of Contents
New projects
Tips and Pitfalls
Example code, i.e. show how to configure a timer for a blocking delay
Complete projects, i.e. control a motor
Humour
Lots of clipart to break up boring text
Links to other sites
Beginners section
How to get started
Note
I recommend that you find the STANDARD for hardware naming for your Forth and stick to it because your example source code won’t be otherwise be portable. Resist the temptation to invent your own or shortened naming for this reason.
Conclusion
Remember, we who use Forth are keeping the simple, the straightforward and the affordable alive in these days of massive complexity, expense and unreliability.
Many people barely know how to design or program and hardware/construction skills are being lost at a massive rate … help keep these skills alive for the next generations, pass on what you know, while you still can.
