I don't know about you, but I send a lot of links to my coworkers about why I've chosen to build something a certain way. Here's how to take that kind of research and turn it into reference material.
For 10+ years in school, I wrote a lot of research papers and had to follow a couple style guides.
In middle and high school English class, it was the Modern Language Association (MLA) style guide. While doing psychological research, I had to follow the American Psychological Association (APA) style guide. One that I have not used but is often used in publishing is The Chicago Manual of Style (CMOS).
Like the PEP has rules for writing Python, style guides have rules for writing up your research. They include things like punctuation, how to group your paragraphs, sections you must include, and best practices. They often exist to communicate industry expectations you must meet to get published.
Most relevant to writing up your research, they have guidelines for how to cite your sources. They cover concepts like using short and long quotations, paraphrasing, and reference lists if you'd prefer to use those over in-text citations.
Because I'm not aiming to get published in a psychological journal anymore, I have more freedom in how I'm citing my sources in my technical blog writing. However, developers (including me) love being technically correct, so my goal is to link to something backing up every assertion or paraphrase I write.
I use direct quotes more rarely in my technical blogging.
"Luckily, I was able to attend Todd Libby's Lunch and Learn. ...Todd said 'No site is 100% accessible, especially as you update it, but we can aim to get close,' so let's aim for close." - Accessibility Auditing My Portfolio Site - Part 1
Paraphrasing flows more naturally.
"Both types of compression support transparency and provide smaller images than PNG or JPEG compression." - What is WebP?
I also link to things I think a reader might want to know more about, like larger technical concepts and packages I'm using.
"In this way, the browser is functioning as a runtime environment for client or client-side code." - A Beginner's Guide to HTTP - Part 1: Definitions
The Note Card Method
I am forever grateful to my middle school science teacher who took us to the library and walked us through how to take notes on note cards for writing research papers. Each note card was for one or more quotes you would use in your paper. Additionally, it would include the information you would use to cite it - the author, the page number, and the title of the book (or a code or abbreviation if the title was really long). That way, you could use your library time to research and write the paper itself later.
Since we're mainly digital with coding blogs and not following a specific style guide, we can just copy that information and paste it into the blog while we're writing.
The title of the book translates to a link.
Instead of a page number, we'll want to link to specific part of a page. You can use a URL fragment identifier if there's a heading. If not, a text fragment will work. You can easily make one with copy link to highlight. You can even include the author or publication in your link text.
Put all together, a direct quote looks like this:
[According to the World Wide Web Consortium](https://www.w3.org/WAI/standards-guidelines/aria/#:~:text=more%20accessible%20to%20people%20with%20disabilities.), WAI-ARIA, the Accessible Rich Internet Applications Suite, aims to make the web "more accessible to people with disabilities."
Some paraphrasing and defining an acronym with a link looks like this:
I would be remiss if I didn't mention your primary job while researching is evaluating your sources. Everyone has bias and a point of view.
Say you're looking to write an unbiased review of a development tool. You're unlikely to find anything critical of the tool on the website of the company that made it. You may find a big list of cons of using that tool on a competitor's site, but none of the pros. Neither stance is particularly nuanced, but together they provide a picture that you can use to start evaluating the tool.
I copy code from Stackoverflow with the best of them, but I got the advice early in my programming studies that you always want to type out and understand the code you're using. This goes double for code you're publishing. Always run it to make sure it works. More than once I've caught a mistake or misconception just by running every code block I'm about to publish.
Reference documentation or the specification for a programming language is usually a safe bet. You just have to check the version and last edit date. We all know from experience how easy it is to let documentation fall out of date.
I hope this answers @teejay128 's question on Writing a Technical Blog.
Furthermore, I hope this encourages those who feel they have to be an expert to write more blogs. Hundreds of research papers taught me you just need to cite and think critically about what you're citing.
Top comments (4)
Really fantastic series Abbey, thank you for sharing!
For a long time I've allowed a sort of imposter syndrome to hold me back from releasing more content - I kept falling down the rabbithole of "I need to be an absolute expert in this specific topic and all related topics before I can publish this post" and it was killing my velocity and motivation to blog
I didn't have a name for it but by doing my own sort of variation of the Note Card Method I've been able to significantly focus the scope and depth of my research allowing me to turn out higher quality content on faster timelines (which in turn keeps me motivated since I'm not spending 12 hours on a relatively short post anymore lol)
Again, thanks so much for shaing! :D
Thanks so much Abbey
You answered my question and more
I am going to try to add more referencing in my next article, I should also try the note card method too
Thanks once again, it was such a great read ❤️
Yay! Thanks for reading!
This is simply an incredible article about writing your own research. Too bad I found it to late. So much good advice in one place. I especially enjoy reading about work in library and making quote cards. I'm used to doing everything with help of online sources, and these cards are something new for me. I understand that there is still a lot of work to be done in developing my writing skills. I used this site assignmentbro.com/ca/do-my-assignment for my own research because I didn't have a sufficient level of these skills. But I still have to work on it. Thanks for the tips. With their help, I will be able to do my assignment better in the future and write good research and blog.