Updated: 2023-12-28
Explore these tips to elevate the formatting and content of our articles. We are in the process of refining these guidelines and welcome your input. Don't hesitate to share your comments or questions about navigating and making the most of this site's features.
A. How to embed an image properly?
Our goal is to clearly see it. Especially for code images, codes must be clear.
Try to not waste empty spaces horizontally and vertically. If you are using visual studio code, or any other IDE, minimize/adjust it such that the code fits without too much unused space. Then capture it with your favorite image tool such as Window's Snipping Tool, etc. I use Greenshot.
This is how the images would look when published.
Visual Studio Code
Online Compiler/Debugger
B. Vertical distance between Image and our markdown divs
To enhance our article we provided some elements with classes div-xxx, where xxx can be "green", "red", "blue", and "faq".
Check the vertical gap between the lower image border and the upper border of the div-blue element. It should not be too close or too far.
output
Check the distance between image and the element with class div-blue.
C. Vertical distance between our markdown divs and an h2 header
code
<div class="div-blue">
<span class="alert-header">Note:</span>
<span class="alert-body">Check the distance between our markdown and the h2 header.</span>
</div>
<h2>Correct formatting</h2>
<p>Formatting is essential ...</p>
output
Check the distance between our markdown and the h2 header.
Correct formatting
Formatting is essential ...
D. In-text Citation and Reference
To gain trust from our readers we use in-text citation and reference as much as possible in our articles. There are many standards in citation styling, there is APA, MLA, IEEE etc.
I like the simplicity of IEEE style so here is an example. Let us say our article involves the TypeError exception in Python. We would like to define it based from the Python documentations and include our interpretation so that our audience can understand it without too much difficulties as Python documentations can be very technical.
start of sample article
A TypeError is one of the exceptions or error in Python. It is raised when an operation or function is applied to an object of inappropriate type. [1] If we try to get the sum of 5 + "7" we will encounter a TypeError exception as the "+" operator does not process if one operand is an int or integer and the other is an str or a string.
What is the Problem?
...
How to solve the problem?
...
Conclusion
...
Reference
[1] "TypeError", https://docs.python.org/3/library/exceptions.html#TypeError (accessed 2023-12-19).
end of sample article
1. Supper script as in-text citation of IEEE
We can use the sup html tag to create the in-text citation.
<sup>\[1\]</sup>
The backslash before the bracket is needed to see the rendered brackets correctly.
2. Reference of IEEE Citation
The format for reference line is this:
<[#]> <Authors> <Title> <Site Name> <Link> (<accessed <date>>)
In the example I just removed the Authors and Site Name fields and create an informative Title. There are some tools to generate IEEE citation. One of those is scribbr citation generator. It can generate manually and automatically.
E. Markdown list with strong tag
editor
* Buy <strong>softwares</strong>
* Read books
output
F. Article Outline Structure
We put effort into organizing our articles in a way that makes them straightforward and quick for our readers to follow and understand.
Typical general structure for solving issues.
<h1>Title</h1>
The title is taken care of by the system.
<h2>Introduction</h2>
<p>Blah blah blah ...</p>
You may remove the <h2>Introduction</h2> and just start its content immediately.
<h2>A. What is the problem</h2>
<p>Blah blah blah ...</p>
If the problem is broad, subdivide it with h3 tags.
<h3>1. Problem number 1</h3>
<p>Blah blah blah ...</p>
<h3>2. Problem number 2</h3>
<p>Blah blah blah ...</p>
Add item number to h3 subdivisions if there are more than one items.
<h2>B. How to replicate the error message</h2>
<p>Blah blah blah ...</p>
If the error message arises from different situations, subdivide it with h3 tags.
<h2>C. How to solve this issue</h2>
<p>Blah blah blah ...</p>
If there are many ways to solve the problem, subdivide it with h3 tags.
<h2>D. Conclusion or Summary or Key Takeaways or Final Thoughts or Wrap-Up or Next Steps or Lessons Learned</h2>
<p>Blah blah blah ...</p>
<h2>E. References</h2>
<p>Blah blah blah ...</p>
We would like to use uppercase letters in the H2 tags and include numbers in the H3 tags, helping readers to quickly spot topic changes and track their place in the article.
Avoid h4, h5, and h6 tags, the article may lose readability since human readers have difficulties in maintaining the structure beyond the third level of subdivisions, leading to challenges in both visual navigation and content comprehension.