loading...

3 Tips for Writing Great Tech Posts

Brian Rinaldi on May 23, 2019

Writing can be difficult. Writing about technical topics and code presents unique challenges. For instance, while code may be engaging to write, it... [Read Full]
markdown guide
 

Hi Brian! This article is great and I absolutely needed it seeing as I just completed editing a technical article I wrote. I was really conscious of a few things.

  • Making sure my language is not too technical and beginner friendly
  • Adding a handful of images or gifs like you mentioned
  • Also adding links that'll further explain the concept and writing about.

I had a few concerns and I'll like to know what you think.

When writing a post that has heavy technical content i.e code blocks. What do you recommend?

  • Having the entire code block in the article? an example using vue will you recommend adding the template, script, and style in the code block?
  • Adding only the relevant code for that paragraph and adding a link to the GitHub Repo.
 

Thanks Egwuenu! For the code blocks, if the entire block isn't relevant to the discussion, I'd include only the relevant portion and a link to GitHub for the full source. Sometimes I even replace irrelevant portions, like inner code on functions or elements, with a ..., though this should be used carefully as some may find it confusing if it hides a portion of code that would improve their understanding.

 
 

I think we should always strive to make it easy to understand besides avoiding technical jargon.

 

Indeed, if it can be said simply then it should be said simply.

code of conduct - report abuse