loading words...

May 27, 2019 17:58:52

Programming Is not Easy.

by @brianball PATRON | 274 words | 389💌

Brian Ball

Total posts: 389💌
Total words: 107477 (429 pages 📄)

Re: Online Tutorials:

Software tutorials are hard to write because it's hard to write down the hundreds of little things you do.


I can imagine, you're trying to right down every step and then you realize: 

oh, I need to install some thing.

oh, I need to update a thing.

oh, I forgot a comma

oh, the code I'm writing in the tutorial is not the code I'm using on my machine, because ...


You forget how precise you need to be when talking to the kind of people who's brain wants a tutorial. Often, it's the very beginners who are trying to make something work. Even when they finally do make the thing work, they don't have command of the tools.


I need to write some tutorials. God knows I've read enough. I imagine it's a lot of work to become somebody who can write thorough, easy-to-follow docs. 

Docs that can be followed from beginning to end. 

Docs that attend to the assumptions.

Docs that keep up with the changes in technology.

Docs that tell you what's important to pay attention to and what's just boilerplate code that is written for you.


In today's coding world, there are thousands of lines of code to complete even basic tasks. Most of those are hidden away. Most don't cause errors. But, sometimes they do. Sometimes they do. Then, you're stuck googling and downloading updates and fixing your code.


I wonder if it was satisfying to program when there were paper punch cards. I imagine you had to have a superior level of organization and clarity of thought. I guess it's the same today. It's not easy.


  • 1

    @brianball There is definitely a space to be filled between "hardcoded" tutorials which suffer from everything you've described, and stackoverflow forums. Some kind of combination of both. Most tutorials are enriched by a comments section which try to answer specific questions and address deprecation issues, etc. But the model can surely be improved upon!

    svenka avatar svenka | May 28, 2019 10:43:11
contact: email - twitter / Terms / Privacy