Please add examples with Ash documentation

Ash Forum Ash Chat
,
1

First of all: I am a mediocre programmer. I am aware of that fact. I don’t try to hide it. But I also know that the majority of programmers out there are mediocre or worse. So I want to be a voice for them (us).

Second of all: I don’t use Ash every day. I use it and then I switch to something totally different because my work asks for it. Between my Ash programming there can be 12-16 weeks of Ruby on Rails programming. Sprinkled with some other programming languages or frameworks. That is the live of a consultant.

I am writing this post to share some light on the main problem people like me have: A ton of documentation we don’t understand. Mainly because most of it doesn’t contain a single working example. Maybe this is a generational problem. Maybe it is a language barrier problem.

Generation Problem

I started programming in the 1980s. In a time without internet. In a time without peers I could ask (I was for a long time the only kid with a computer in my home town). Books about programming were a) expensive and b) had to be ordered from the US (I live in Germany) which was a BIG deal in those times and it took weeks. I mainly learned by reading programs I found in computer journals. On printed paper :scream::wink:. For context: My first computer was a ZX 81 and didn’t had a storage devise. I learned not by theoretical explanations but by examples which I refactored. Give me a Hello World! and I thank you! In 9 out of 10 times I use Google to search for an Ash problem. Most times I find a “solution” but one I do not understand. If they included a working example it would make a huge difference. And by working I do mean working. Not something that looks like a working example but actually is missing a couple of key components.

Language Problem

I am German. I feel fine to communicate in English but every now and then I don’t understand a technical term. With a clean and working piece of example code I wouldn’t even have to understand the term. It would make such a big difference.

Bottom Line

I just wanted to share some light into a frustrating situation for us mediocre programmers who want to use Ash but who get stuck so often. If you read a question of us do not assume that we are too lazy to search for the answer but please assume that we really don’t understand what we found and give us a working example code which we can play around with. I don’t need to understand the 100 possible arguments of something. I only need a solution for my problem and from that I can go ahead and learn additional stuff.

8 Likes
2

This is something that I will be aiming to improve soon, primarily by overhauling our reference docs. This is one of the things that is next up on the docket.

7 Likes
3

There is also an aspect here of the methodology behind support. The way that we help people on forums etc. is not necessarily by providing a fully worked solution to their problem.

Please don’t get frustrated when someone links you to documentation they think will help. This is what is supposed to happen first. You can say “I read that but I don’t understand it”. And that gives us information on what needs to be improved on the docs. But just writing out a code example in response to a question is not how our documentation improves.

We don’t have full context of someone’s app, we don’t know what else your code base contains, or what else you do or don’t know. From your perspective you have one very simple problem and you know exactly what you don’t know. But we deal with folks at various skill levels with Ash all the time.

Regardless, as I mentioned in my original response, we have an explicit goal of going over all of the docs and adding examples to as many places as possible. Hopefully that will make some of this easier.

6 Likes
4

From another fellow mediocre, non english native and ZX81 imprinted programmer, I hear you, thanks for putting this feelings in simple words, thus lifting some of my impostor syndrome out of me. Also many thanks to all the good and excellent programmers that, at the end of the day, have made and still make my programmer life so much easier :peace_symbol: :purple_heart:

3 Likes
5

I’m a native english speaker, and I also feel some of the pain when looking for minimal Ash examples.

One of the things that’s been helping me is reading through the Dsl docs on Ash’s docs.
For example this doc (DSL: Ash.Resource.Dsl — ash v3.4.36) has all of the different statements you can put inside of an ash resource.

Looking through that list helped a lot in terms of understanding how to set up Ash’s different featuers.

2 Likes
6

Check out Build something with Ash guided by Zach Daniel!.
Shout out to @PJUllrich and @zachdaniel, they made a great walkthrough. Haven’t watched it fully yet but I’m sure I’ll learn something along the way. :slight_smile:
git repo

5 Likes