So this is a bit of fun on a Sunday in response to this article on clean code from @cleancodestudio 😋.
To be clear, the tips in the article are great, this is purely a post pointing out that tweet threads as DEV articles don’t work!
There is no hate or malice here, I am just mischievous (as most of you know) and the article had loads of accessibility issues caused by embedding a load of tweets...so you know I am going to have to say something being the "angry accessibility guy"!
Anyway, it is silly with an important message, please treat it as such!
Here is my list of 10 tips for clean articles on DEV! (I would suggest going to read the article first or read them at the same time, otherwise some of these points may not make sense!)
The Tips
- Don't repeat the article title immediately within the article body, we know what we are reading and it just adds noise
- Don't add alt descriptions to decorative images (the down arrows) used as spacers, instead do
and leave thealtattribute empty - they add nothing for people who use a screen reader and get annoying the 3rd, 4th, 5th etc. time. - Better yet just don't use spacer images, if you structure your article correctly with headings it will be easy to read.
- Including more than one or two tweets from the same account means a lot of repeated information for people who use a screen reader. This makes your article hard to read and tiring, instead copy the content of the tweets into your post.
- Use headings for each point or, as I am doing, an ordered list to make navigating the items easier.
- Put all 10 tips within the article itself (which you can do if you do things properly, there is a reason DEV stops you adding more than 7 tweet embeds!). Having to hunt through the comments for the remaining tips is annoying (due in part to how the DEV comment system works in ordering things).
- On a similar point, comments can change order in the DEV comments section so don't use it for anything that that relies on the order of the comments to make sense.
- Don't use 10 fire emojis in a row in a comment, for a person who uses a screen reader the effect is quite annoying, surely 3 or 4 would get the point across? 🔥🔥🔥🔥 Don't try and "outfire" people without thinking of how that affects others!
- There are no word limit counts on DEV, you can use full sentences to explain things, rather than having to worry about every character. Enjoy this new found power to express yourself properly and make things flow!
- You are responsible for the quality of your posts, not DEV, not your manager, you. So use the extra tools at your disposal to turn tweet threads into high quality posts that everyone can enjoy.
The End
Obviously this may all be a bit of fun but the points are all valid and important (I might have had to stretch a little on the last two, maybe 8 valid tips and a coupler of filler tips - but that wouldn't make a good title now would it? 🤣).
Advice for everyone: put some effort in to formatting your articles properly, it makes them easier to read and also has the added bonus of including everyone in the conversation!
And yes, for those of you who read the original article, I did even copy the cover image style and design, if you are going to copy someone's work do it right! 🤣
Bonus Tip 11
Always have a bonus tip, people seem to love that!
My bonus tip is to follow @cleancodestudio on Twitter, I just have as they put great tips out!
Oh and I have few followers (although I only started using Twitter again this week), so you could always follow @InHuOfficial if you fancy it, my silliness will continue there.
Hope this article made you smile and I hope you are having a great weekend!
Update
@cleancodestudio has copied this post style and content in a funny and engaging way, while still managing to produce a great set of programming related quotes! You should check it out!
Top comments (36)
Sorry @cleancodestudio , I just had to!
I hope you find the tips useful! Followed as I said in the article, I look forward to reading more awesome tips from you....as threads on Twitter, and as articles on here! 😉
Oh and this screenshot was just too good to not share with you:
Calling me out on my ish @inhuofficial 😮💨!!! Feelings hurt and emotions scarred man, not cool hitting me with all that honest feed back within a single post.
Lol, on a real note - I love it man. You're points are valid and I had a feeling going in that I may be called out on that post for it's structure. You make very sound arguments against my articles structure.
Point number 8 was an insightful one, I wasn't aware that multiple emoji's lined up continuously would mess with a screen screener. Thinking about it now, thanks to your post, that definitely makes since. Having that read off to you would be not only confusing, but I'd go as far as to say it'd be annoying as hell.
Would have never taken into consideration screen readers if you would not have referenced them as a point of note in your article - so thank you for that. I'm going to leave the comment up as is so that readers of your post have a reference to what you were writing about.
In the future, I'll take note of screen readers and not follow a similar pattern that would annoy visitors digesting the content via screen readers.
You make great points, but I would be remiss (and boring) to simply say you're right and I'll fix it moving forward. That's no fun, and I may try some crazy structure's in the future to see where the cards fall.
The Defense Has The Floor
1: I know how to structure an article
Before I was a software developer, I was in SEO (Search Engine Optimization). I understand everything from the structural breakdown (header tags, meta tags, keyword analysis percentage, linking to credible sources, on page user interaction, etc...) all the way to the more important user engagement techniques.
I spent over two years writing articles, comparing the analytics, and then re-adjusting my strategy to improve the engagement of my posts from the readers perspective.
Between my heavy SEO experiences professionally, receiving a national writing award for a cheesy creative piece I wrote dubbed "The Paradox at Breckenridge", and my cough cough perfect 36 on that English section of the ACT - I'd say I'm at least at par when it comes to blogging.
36 on the ACT for English...a pretentious point to make?
Absolutely.
Is my ego feeling a little bit better now? Hell yes it is.
So now, instead of making pretensions and pointless references to my extensive SEO experience, national recognition as a creative writer, or pointing to - by definition of the ACT (that high school test I am way too damn proud about) - my quite literal perfect understanding of the English language; I'll instead simply point out this statement.
I know how to structure an article.
For reference, here's how I structure and present articles that I intend to share as (semi) professionally written pieces.
The (Most Comprehensive) JavaScript Design Principles Guid
This leads me to point two of my defense.
2: I wasn't writing an article
I don't believe in always writing articles perfectly. I believe in writing articles when the content should be shared as an article. As another example of an article - here's one I wrote on Promises.
This is How [JavaScript] Promises Really Work
What's not an article is this post that basically indexes 100+ the Clean Code Studio screencasts I've created on a single page.
100+ (Clean Code Studio) Coding Screencasts
My intention, quite clearly, wasn't to write an article. My intention wasn't to invest time towards structure. No, instead, my intention was to plop a whole bunch of content I've created through other channels and simply share that content with my dev.to community.
I've already done the footwork and created the content, I don't want to invest 100 days to write 100 blog posts, about 100 screencasts I've already spent 100+ days creating.
That's non-sense.
This leads me to point 3 of my defense...
3: Document, don't create
I choose to simply post my personal thoughts already shared from other social platforms OR to simply add my personal documentation to dev.to. Here's another dev.to post I created that is not an article.
Sure, it may come across as an article, but in my mind it's simply not. I haven't audited the content I've posted in it, put any great amount of thought to the post itself, nor tried to structure it outside of the basics.
Check this non-article out:
Arrays, hash tables, linked lists, queues, stacks, & Trees (My repl.it playground while studying for FAANG)
This post simply shares a repl.it repo. It's the repl I created and used while studying for my Google, Facebook, and Amazon interviews. I'm not even sure all of the data structures and algorithms in the repl work properly (as noted in the post).
That being said, I would've killed for someone's personal notes while I was going through the FAANG interview process.
Knowing this, after I landed at Amazon, I decided to start posting my personal notes from my personal FAANG interview experiences.
I'm not trying to re-create my notes, I'm not trying to formalize or turn my notes into professional level articles. It'd take too long and I'd never actually get to it unless I decided to invest 6+ months into formalizing them.
If I took the time to finalize my FAANG notes into some kind of final piece of content wouldn't it be better though?
Of course it would, and eventually I'm hoping to get to a point where I have the time to do that kind of thing. But, in the mean time - I'd rather put out content that has valuable even in its imperfect organic state compared to put out no content at all when I have hundreds of pages of valuable content. I could hold off and say "I can't put it out until it's perfect". Or I can say, here's my personal FAANG interview notes - it's not perfect but it's got a ton of valuable content for you throughout. It's raw information. It's also shares my raw perspective in a way.
It might not add value directly to you as an individual or developer, but maybe sarah smith finds a snippet in there that she's been looking for and she finds value.
The way I see it is like this - I have a full time job and a life. I spend 15 to 20 hours of my free time posting free content to the world each week as it is right now.
I don't have time to go through everything I've learned, audit it, structure it, and finalize it down to its most simplified and digestible format. In fact, most of my content isn't ever going to be simplified down to to its most digestible format. Not a single one of my dev.to articles is created to the best of my ability, not a single one. That hurts a little bit - but I also know that my experience writing and with SEO balances out the fact that I'm opting to put as much value out there as I can and in doing so have decided to refrain from reaching for perfection when the content I'm perfecting is extractable without that extra effort.
I've created 50+ open source repos on github, published 20+ of those packages to npm and packagist , written 40+ dev.to blogs, and have recorded and published OVER 120 Clean Code Studio Screencasts.
The truth is, I do as much as I possibly can to try to deliver the best content I am able to - but I do not have the time nor the physical capabilities to constantly work 90+ hours a week, no matter how much I love it.
I have so many articles, concepts, and thoughts about the industry as well as my personal experiences that I'd love to be created to perfection before being shared. But,, if I waited until everything was perfect....then I'd rarely ever share helpful information.
I gave up trying to create content every day. I create content maybe 3 to 5 times a month. Those are the well thought out, structured, and simplified pieces of content. I make sure to save that kind of content for topics that really need them.
I decided to start documenting and stop creating.
What do I mean by that truly?
Well - turns out - I took over 200 pages of personal notes during my FAANG study prep. This doesn't include the 100's of files of code I wrote - this is literally documents I stored in my google drive with notes on FAANG.
200+ pages of my personal notes during a time where I was doing my best to nail a FAANG job. Three months plus of preparation, too many all nighters to count, and tons of valuable information throughout.
I started trying to create a single article about it (one hell of a long article) - it wasn't going to happen. 200+ pages is a lot for most e-books now a days.
Instead of making the perfect structured article, I decided to take a different route.
I added a new page on my website called Notes. Under notes, I made a sub page called "FAANG Interview Notes".
On this page, I literally plopped all my Google Drive notes out for anyone to read. They might have some parts where thoughts or code is incomplete and they're definitely not perfectly structured -- BUT it's 200+ documents of personal notes and learning experiences through my own trial and error going through the FAANG interview processes.
Everything from data structures & algorithms, to behavioral questions, to the questions facebook asked me during interview, to Amazon's leadership principles, to Google's recommended study resources they send you directly upon entering into their interview process, etc...
There's so much valuable information that it will take me half a year to organize and formalize. Eventually, I plan on actually doing that because it's enough content to make a highly valuable course out of.
By simply sharing my notes, others have access to this information to prep for their own FAANG interviews. Waiting to make everything perfect would starve the dev community of high value information.
On the other hand, for topics like a simple list of 10 one line sentences explaining some really basic stuff - yah, that kind of content I just try to share and get out to the world.
Would it be better simplified? Absolutely, does simplifying a post like this take away from me being able to simplify a more complex topic that would be more beneficial to my follower base - also absolutely.
The truth is, like sharing a post from dev.to on to twitter - I simply reversed it. I used dev.to's liquid tags to simply and quickly add a post that showed some tweets I made. Those tweets have useful content in them and it's not hard content to extract. I don't want to invest my time to simplify something everyone will already get because it's not a valuable investment of my time for anyone and it's frankly boring.
As far as the arrows go that break up the tweets, I was actually messing with the center tag element that allows you to center text within dev.to blogs. I was curious how it worked with images and whatever else was on my mind at the time - the arrows are there because I was tinkering with centering images as well as text and simply decided to keep the centering because it was something that I haven't seen in other dev.to blogs yet.
I simply shared some tweets from twitter. Saw a new feature that could help my dev.to content and was fun to tinker with and together that formulated the post you're posting on. I didn't feel like an article needed to be written to share the simple, but useful information that users found in those 10 Clean Code Tips tweets.
I wanted to share my thoughts, already created on twitter, to my dev.to following. If I wanted to write an article that was structured and detail out the nuances of a coding concept - I would've done that (as I've done in many of my several posts on dev.to like the resources linked above).
This wasn't me writing an article, this was me sharing some thoughts into a community that happened to be dev.to from another community which happened to be twitter.
To be honest, this comment is more of an article than those tweets I posted - and that's okay because the general feed back on that post was positive. People were able to extract the Clean Code tips, feel like they learned something new, and move on with there day.
Then there's some other mischievous writers out there that do what they do -- which really has me thinking...
..how bad can the article content be, if the one throwing shade at this article content, decides to use the banner from the article their talking about, to ultimately make their article look 5x better than it would have without that cover image.
The content aint good, but it's still good enough to use in your own article for your banner , if you ended up using parts of it within your own post - low key that banner might be the best looking thing on this whole page if you ask me 😉
OK I read that whole essay, loved it!
Oh and as for being pretentious telling me your achievements...certainly not, people need to stop worrying about shouting out about what they have achieved!
Yes, I too have literally just been playing with centring things 😉dev.to/inhuofficial/comment/1h2m6 -
<center>may be deprecated but while it works, take advantage!As for the main point, getting content out there. I agree, share stuff with the world when it isn't perfect! Better out in the world and not fully accessible than not out there at all (a shocking thing to say coming from an accessibility advocate!)
The only argument I have is that adding all those liquid tags would take a similar amount of time to copy pasting the content and adding a couple of headings. It isn't a 200 page books worth of information to adjust so I am sure 2-3 minutes of your time would have been worth it.
But that is it, the whole argument, I am merely prodding (in what was meant to be a playful manner) you towards thinking about accessibility. If it read in any way other than playful then that is my fault, I write rants often that are meant to be angry so I think my softer side is beginning to weaken! 😋🤣
Oh and when I said article, I didn't mean a masterpiece, just the best format for the platform you are posting on so that everyone can digest the information easily.
An option while you experiment
You do know that one option would just be to link to the original twitter thread as a way of providing a more accessible alternative? A simple disclaimer at the start of the article:
"Due to limitations on how content can be added to content sharing sites like DEV, this post may not be a great experience for people who use assistive technology such as a screen reader. As such you can find the original thread on Twitter here as that may be more accessible."
Still not perfect but at least a nice heads up for people and a simple way that you could partially address the issue while playing around with ideas!
Look after yourself
Oh and a final thought just based on a couple of comments you made in that epic rant, take some time for a break.
90+ hours a week and all-nighters are the road to a miserable existence and burnout. Take some of the pressure off, you have plenty of time to get the content out there!
Look after yourself!
If I have misread that, then ignore me, just a friendly reminder based on what you wrote that 1000 posts over 10 years is much better than 100 posts in 3 months and then stopping producing content as you are sick of it!
I look forward to seeing more of your posts and seeing the course based on all of your notes when you get that finished!
@inhuofficial I re-read my reply on this and realized I may have missed your point to an extent about accessibility (running on fumes after an all nighter).
Are tweets shared via a dev.to post something that will make the page inaccessible all together for visitors using screen readers?
If I wasn't able to easily share the tweets via liquid tags, I most likely wouldn't have made the post. It's reached over 1600 readers in less than 24 hours and seems to be adding value to readers. Is that value completely inaccessible to users using screen readers?
Were the tweets less accessible or completely inaccessible?
No no, not completely inaccessible at all. Just a bad experience.
The values is there, I really did try to make it clear it is only the use of embedding tweets that is an issue, the tips are top notch!
I am certainly not suggesting you should do anything drastic.
They are just tips that instead of embedding the tweets you should turn them into an actual article and copy the content in as it will be more accessible and nicer to read (plus like I said about having to add things to the comments...you won’t have that problem.)
It would have been quicker to copy paste the content and format it.
I am certainly not saying not to post it, just suggesting better ways to do it that I would hope will result in even more upvotes and by extension, even more views!
Appreciate your feedback @inhuofficial , also (as a small plug) everyone reading this comment needs to check out @inhuofficial 's PHENOMINAL article on accessibility!
dev.to/inhuofficial/101-digital-ac... and follow him on twitter (I do) for some awesome coding tweets!
twitter.com/InHuOfficial
Thanks again for your awesome feedback @inhuofficial , it's appreciated.
Ok I can’t read this one on a phone, I will check it out properly when I get to my computer but it looks like an awesome comment and really interesting from a quick skim read!
Thank you for making this post... 💖
Tip 12, don’t use headings to make your comments text larger, it is confusing for people who use screen readers! 😉🤣
Being serious for a second: I am glad you enjoyed it, when is your next post due, I have been enjoying reading them!
OK
Thank you for reading them !!
At last,
😹
Well I suppose I left myself wide open to that one! 😜🤣
I think there are more comments than the reactions of this post (⌐■_■)
It tends to be that way on some of my silly posts, they tend to breed more silliness (such as people using Headings to annoy me after I point out not to use headings 😉) 🤣
Son -> Typing in a comment field == # Wow excellent post ! Keep it up
@inhuofficial -> Son, don't use h1 for comments. There not accessibility friendly.
Son -> I don't care
@inhuofficial -> ......
What's next ? Is this silly enough ?
🤪
🤣
<mark>my words, if you don't improve the semantics of your<output>on this site, I will have to come over there and give you a<big>smack. This isn't a<small>issue, the<code>you produce has a real impact on hundreds of people, stop thinking you are special or the<center>of the universe.<i><mark>ed your words.<i>know I'm not the<center>So, you should take
<a><br>eak. And use S̴e̸m̵a̸n̸t̴i̶c̵ ̷H̶T̵M̵L̷ ̵e̶l̷e̶m̶e̵n̶t̷s̴ ̸b̵e̸f̵o̴r̴e̸ ̶a̷ ̸c̴u̴r̸s̷e̴ ̵w̸i̷l̷l̵ ̷c̷o̸m̸e̴ ̷t̸o̸ ̶y̴o̸u̸ ̵!̷!̵ %^353The late, great comicbook artist, Carl Barks, once said, that he only released stories, he'd pay for to read himself.
He knew, that 15 cents for a comicbook, were a lot of money for kids (in the 1950's) – so he wanted to give them “bang for the buck”.
I think the same principle should be applied to writing articles:
I've replaced “pay” with ”time” since ”time” – or the lack of it – is the true currency today.
So, the next time you (well, not you, @inhuofficial ) write a “Top 7 Tips for Something”, ask yourself this:
“Would I spend time reading this myself?”
The tips were really good, just the presentation that needed work and I don’t want people to think otherwise.
I better add something to the beginning to clarify that, this one wasn’t me poking fun at listicles for once!
Right now that I have put that disclaimer in the article I just want to say I love this comment as general advice.
Stored the quote away for the series I am writing on blogging at the moment! Awesome advice for all content creators! ❤️
Thank you! 😀
I actually don't care if an article is a bit unorganized/messy, as long as I can feel the passion of the writer!
It always shines through, if someone is truly passionate about something, no matter the topic.
But: When an article is written with the clear intent of getting as many “likes” and tweets as possible, I tend to avoid it!
So you haven’t read the top, super original post that is top of the feed this month?
Surely it shows passion for github and JavaScript and isn’t in any way pandering or looking for likes? 🤣
😂
Hello InHuOfficial,
thanks for your article!
I like your bonus tip as a tip :).
It felt like a nice offer or gift, like when you went to eat somewhere and the restaurant owner gave you a small dessert for free as a thank you.
Enjoy the ice-cream then! 😉🤣
I am glad you enjoyed it and although it was a silly article I hope a couple of the points were useful!
The argument regarding the screen reader is a valid point in my opinion.
Never thought about it.
Tip 8 is a very good example of not overdoing it with emojis. I like this.
Tip 1 reminds me of the DRY (don't repeat yourself) principle. The only difference is that in this case I would call it DRI (don't repeat immediately). Ok, I'm not very serious about defining a new principle here, but I enjoy messing around with thoughts :D. And you seem like a person who can handle some stupid jokes :).
From my point of view, your article has added value, otherwise I would not have liked it and shared it on Twitter ;).
Bonus question(you don`t have to answer):
What does the unicorn mean?
Nobody knows the exact meaning of the unicorn! But the idea is that it is a second like button so if you think an article is good, give it a heart, if you think it is outstanding / excpetional add a unicorn as well.
In the algorithm for ranking articles they have the same weighting so it is "like" and "like" effectively!
p.s. DRI - I think it could catch on! Stored it for future use and I will "try it out" and see if some people start using it! 🤣
11) Do not abuse dev.to's tag system to lure in more readers. Only use tag(s) which are subject(s) to your article. The less tags, the better.
12) Put the full article on dev.to, not a summary with a link to the full article on your blog.
Oh I could have made this 50 points if it was a serious post!
Those are definitely high up the list of things that annoy the heck out of me though!
In fact I wrote a post about this, you can check it out on my blog 😉
#JavaScript, #CSS, #React, #HTML
Okay, okay you get the heart, unicorn, and a book mark -- I just can't deny my ❤️ for that banner @inhuofficial 😉
Appreciate the post, always love to see differing perspectives. I left ya a much larger response further down below.
Could you please take a look on my articles and give a feedback? I am open to criticism so dont shy)
I have scanned a couple of them and you look to be doing loads right 👍, I will try and carve a decent amount of time out to check one properly for you but normally if I scan something and I think it looks OK, it is going to be reasonably accessible!
The only thing is in your latest article dev.to/captainyossarian/how-to-wri... your different sections should be split by a heading rather than just bold text.
So
Part 1 - safer functions
Would be better. Also perhaps (something to think about, not advice!) think about whether "part 1", "part 2" etc. are necessary, if you make them headings they will probably make sense on their own.
Thanks, appreciate it
Wow... InHuOfficial is here to make friends and tell hard truths, and he's all out of friends. 😋
😥
I'm just joking. I should have added the
</sarcasm>tag at the end 😬The post is great, and has really good advice when creating posts on dev.
I don't think you needed to as otherwise I would have to have added the sarcasm tag to my response to you (and about 200 other comments I have made as I am just a sarcastic so and so!)
Don't worry, you can be "mean" to me (as I am sure you can do better than that 😉), I am weird, I like it!