This is a plea to anyone who thinks they want to publish ANYTHING

This is a plea to anyone who thinks they want to publish ANY instructions about anything tech-related; DON’T.

Let me explain my frustration…

The population is divided into two parts, the seers and the blind (otherwise known as the Gibbons).

The seers know about, let’s say yii2, the blind haven’t got a clue, but maybe would like to find out.

So, a seer decides to write an article, instruction or publish source code on say GitHub. While they may be good at coding they are almost certainly RUBBISH at documenting their creation. Almost every article I read falls into the category of miserable (could do better).

Let me show you. “In case you wish to setup one Icon framework globally, set the parameter icon-framework in the params array of your Yii Configuration File.” Where is the params array? What the author needed to add here was a breadcrumb like: “yoursite/config/params.php”.

So if you read this and want to go into print, please, please, PLEASE, consult a Gibbon first.

1 Like

Read better articles, stop reading articles on random blogs from people who are just out to get SEO points.

2 Likes

I agree with @m_hutley that you probably should read better material then. There are some good quality content out there if you wish to look. Even scholarly papers.

One thing I would also mention is that often times tech can be complicated and so when someone writes about a topic, they assume you have a certain level of understanding of underlying principles. You can’t expect someone to teach you all the ins and outs of PHP before talking about PHP traits or inheritance.

So gauge the material you are reading and if it makes you confused, besides jumping to the conclusion that it is poor writing, maybe also think it might be a bit more advanced than you are at right at the moment. It is ok. Everyone is not an expert at everything. I usually read three different articles on the same topic by different writers before I can fully understand it.

3 Likes

You see you have assumed I read Blogs, for which I have no time. My quote above came from GitHub, where authors make assumptions all the time. Please never assume, start at the bottom and work up.

Because an article published on GitHub by any random user suddenly isnt just the user’s blog.

Please never think you understand everything. Start at thought and work up. (Yes, I can be just as condascending as you are.)

Oof… no wonder you are finding bad material to read. Github isn’t there to hold your hand or write top level research content with proper grammar and content. It is there to share code and obviously they are going to assume a lot about the people that read their content. Many times they are not even writing to you and me but to the other devs on the project or domain experts that already know everything underpinning their code.

3 Likes

Do you consider that to be a great example of clarity? Or maybe at least good?

Yes they usually assume you understand what it is they are trying to help you understand. The writer understands it and it seems very difficult for many authors to think from the point of view of someone that does not.

I saw good documentation about half a century ago. Documentation of machine language is especially likely to be clear. I assume the Intel documentation of their processors is good. In the past few decades I have seen very little good documentation. Young people might not have experienced the pleasure of reading good documentation.

I don’t jump to the conclusion but I usually conclude that very few people know how to write clearly, accurately and concisely.

I probably do not understand what you are trying to say there. If I do then don’t complain about not finding anything useful.

That sounds like a deficiency in the original question. You assumed we knew you do not read blogs.

The word blog is ambiguous (confusing). Originally it meant Web Log. Within a matter of less than a couple of decades it has become to mean many things such that now it is confusing. As best as I understand it, a blog can be a diary, an article, an online magazine or maybe other things; maybe even documentation. If you do not want to read anything like that then yes, you will be forever confused.

1 Like

This topic was automatically closed 91 days after the last reply. New replies are no longer allowed.