technical writing - freeCodeCamp.org

How to Use Pandoc – An Open Source Tool for Technical Writers

Vikram Aruchamy — Tue, 09 Jul 2024 15:33:40 +0000

Technical writers frequently navigate the complexities of various document formats and revisions. Pandoc, a free and open-source tool, offers a powerful solution to streamline these processes.

In this tutorial, I'll explain the Pandoc's functionalities, specifically focusing on two key areas that can significantly enhance the workflow for technical writers:

Docs and Markdown Conversions: If you write in Google Docs to leverage their collaborative writing, editing, and review features, Pandoc empowers you to convert Google Docs into markdown for publishing needs, and if you write in markdown, it helps you convert markdown to Google Docs or Microsoft Word for creating deliverables.

Merging of Multiple Docs into One: If you work in the "content as component approach", Pandoc allows you to merge multiple Google Docs into a single document with a few commands for publishing needs.

You can also create scripts to automate these processes.

Why Use Markdown for Technical Writing?

Markdown is great for technical writers because it simplifies the writing process and improves collaboration. Here's why:

Readability and Ease of Use: Markdown uses plain text symbols for formatting, making it clear and easy to learn. This lets you concentrate on writing clear content without getting caught up in styling complexities.

Platform Independence: Markdown files are plain text, allowing you to write in any text editor on any device. This flexibility provides freedom in your writing environment and eliminates software compatibility concerns.

Seamless Conversion with Free Tools: Free tools such as Pandoc offer format flexibility for markdown users, such as converting markdown to Google Docs, Word documents, or HTML, ensuring compatibility with collaborative editing needs and final deliverables. This also extends to modern workflows, where large language models generate content in markdown. You can use ChatGPT or the Gemini API for creating initial drafts, integrate them with your writing, and then use Pandoc to convert the final document to Google Docs or Microsoft Word for team editing, feedback, and creating deliverables. This streamlined workflow empowers efficient and collaborative content creation.

Version Control Friendly: Markdown's plain text nature enables seamless integration with version control systems like Git. This facilitates tracking changes, reverting to previous versions. This is particularly valuable for technical writing projects that often undergo revisions and involve multiple team members working on different sections.

Why Merge Multiple Documents into One?

Technical writing often involves creating complex documents from smaller, reusable pieces. We call these pieces "content components." These components can be individual chapters, user guides, reference articles, or any other modular unit that contributes to the final product. In other words, content components are building blocks for bigger projects.

However, writing tools such as Google Docs lack the ability to merge these components into a one document. This can be a major hurdle for projects like:

Technical Documentation: Building a user guide by assembling and reordering pre-written topics rather than crafting the entire document from scratch.
Reference Guides: Consolidating multiple articles from a knowledge base into a single, printable reference manual.
Book Authoring: Constructing a book by compiling individual chapters and appendices, streamlining the writing and editing process.

In all these scenarios, the need to merge content components becomes crucial for creating well-structured and efficient documentation.

How to Install Pandoc

You can install Pandoc on your system using the packages available in the releases list. The installation page has a detailed tutorial on the steps to install it on different systems.

Once Pandoc is installed, you can use it in the command line to perform different document conversion operations as explained below.

How to Convert Markdown to Word or Google Docs

To convert a markdown file to a Word document or Google Docs using Pandoc, follow these steps:

Open a terminal or command prompt and navigate to the directory where your markdown file is located.
Run the following Pandoc command to convert your markdown file to a Word document:

pandoc input.md -o output.docx

Replace input.md with the name of your input markdown file, and output.docx with the desired name of your Word document.

To convert the Docx format into Google Docs, you can upload it to Google Drive and open it in Google Docs.

With these steps, you can convert your markdown files to Word documents or Google Docs using Pandoc.

How to Convert Google Docs or Word to Markdown

In this section, I'll explain how to convert a Google Docs or Microsoft Word document into arkdown format.

While the Docs format is accepted by Pandoc, you cannot use the Google Docs URL directly with Pandoc. Therefore, you need to export the Google Doc into Docx format.

Go to File > Download > Microsoft Word (.docx) in your Google Doc to download the document in the .docx format as shown in the following image:

option to download document in .docx format

Now you'll have the Word document equivalent of the Google Docs.

To convert the Word document to markdown using Pandoc, run the following command in your terminal or command prompt:

pandoc input.docx -o output.md

Replace input.docx with the name of your Word document, and output.md with the desired name of your markdown file.

How to Merge Multiple Documents into One

To merge multiple Google Docs or Word documents into a single file using Pandoc, you can follow these two steps:

Convert individual documents to markdown using the Pandoc conversion command to convert each Google Doc or Word document into a separate markdown file (explained in the previous section).
Once you have individual markdown files, use the following Pandoc command to merge them into a single document.

pandoc file1.md file2.md -o merged_output.docx

Replace file1.md and file2.md with the names of your input markdown files. These files will be merged into one merged_output.docx.

You can use your desired output format instead of merged_output.docx based on your goals. For instance, you can create a single HTML file if you intend to publish it on the web, or use the markdown format if your publishing platform supports markdown.

This approach leverages Pandoc's strengths for format conversion and merging to achieve the desired outcome of a unified document.

For more information and helpful answers about using Pandoc, check out the Pandoc FAQs.

Conclusion

In conclusion, Pandoc is a powerful and versatile tool for technical writers, offering document conversion and merging capabilities.

With its ability to convert Google Docs into markdown and merge multiple documents into one, Pandoc streamlines the process of creating and publishing technical documentation.

How to Become a Technical Writer – A Guide for Developers

Tooba Jamal — Thu, 20 Jun 2024 15:54:28 +0000

Being a top-notch developer was my dream – until I realized I could combine my passion for writing with my technical knowledge to earn a living. That's right: I'm talking about becoming a technical writer.

And if you're a developer, you may be in a good position to get into technical writing if it's something that interests you.

Developers have a lot of knowledge about topics like Git, Markdown, programming languages, and IDEs that they can use to teach others. And since they have worked with these tools and technologies themselves, they can often write documentation with a user-centric approach.

It's also fairly lucrative to be a technical writer, with the average salary in the US being $76,432 per year. This makes it a viable career to support yourself and your family.

Luckily, I had technical writing samples to exhibit my writing skills when I decided to give it a chance. My love for writing offered me a ready-made technical writing portfolio and made my career change easier.

But this is not the case for everyone and people regularly ask me tips to start technical writing and earn through it. So I'm compiling all the things that helped me transition into technical writing in this article.

What is Technical Writing?

Technical writing typically involves breaking down complex technical knowledge into simple words, making it easier for a non-technical audience to grasp technical concepts. The aim of technical writing is to ensure that users can effectively use a technology, which ultimately improves user satisfaction.

As a technical writer, you can write about a wide range of topics and write for different purposes and audiences. Some of the types of writing you may do will include:

User manuals
Documentation
Detailed guides
Blog posts
White papers
SOPs

and so on.

Accuracy, consistency, clarity, and conciseness are some of the crucial aspects of technical writing.

What are the Responsibilities of a Technical Writer?

Technical writing requires extensive research, which can make the writing process longer. Technical writers stay in a loop with Subject Matter Experts (SMEs) to understand the technical details of client products/ services.

After gathering loads of information through expert interviews and research, technical writers compile relevant information into their writing.

After gaining some experience, technical writers might also have to edit and proofread others' writing. Proofreading and editing require patience, attention to detail, and empathy.

How to Become a Technical Writer

Start writing tutorials, how-to guides, and share your experience with technology on an open publishing platform like Medium, Hashnode, or HackerNoon. These blog sites are easy to handle for beginners because they're free and some of their publications have a huge audience base.

If you're unsure about how to write technical articles, start reading a lot of them. This will start to give you the sense of how technical writers share their information in an approachable way, how they structure their articles, what topics they focus on, and so on.

Below are some beginner-friendly blog post ideas:

How to do X in/ using Y (Example: How to build a portfolio website in WordPress)
X ways to do Y (Example: 3 ways to avoid overfitting in machine learning models)
What I learned in 10 days of working with X (Example: What I learned in 10 days of working in VSCode)
A guide to X: Everything you need to know (Example: A guide to AI Website builders: Everything you need to know)

You can also read various publications' technical writing guides. These contain a lot of helpful hints and information about how to write good technical tutorials. Digital Ocean has a pretty well-known one, and freeCodeCamp has their own as well.

Build a Portfolio

Once you've got a few writing samples, you can help build your credibility by creating an online portfolio that contains all your writing samples. This is something you can share with potential employers or project maintainers.

You can share it on social media platforms, display it on LinkedIn featured section, and send to potential clients.

You can also try writing for publications. Well-known publications often have a huge following and they share contributor content on their social media platforms. This can help build your personal brand as a technical writer, grow your network, and motivate you to write more good stuff.

Some publications that accept contributions from new writers are:

freeCodeCamp: freeCodeCamp expects you to have at least three writing samples when you submit a contributor application. The application process is a bit more rigorous than some, and they don't accept every application for various reasons. But if you don't hear from them and aren't accepted the first time, don't give up. You can keep improving your writing, and try again later – or try other publications. You can find the fCC contributor guidelines here.
Towards Data Science: Towards Data Science accepts articles revolving around data science and machine learning. They expect you to submit well-structured, comprehensive, and up-to-date articles. Read the TDS contributor guidelines here.
Level Up Coding: Level Up Coding is an online publication focused on sharing technical knowledge to help software engineers learn and grow. They have an audience of developers, designers, and data scientists so they expect content that's useful to them. Here are the contributing guidelines for Level Up Coding.

Though all publications have contributing guidelines in place to help contributors write relevant samples, a few tips to make your pitch a success are:

Get familiar: Read at least 3-5 top-performing articles in the publication you want to contribute to. Pay attention to the tone of voice and the level of detail shared to understand their preferences.
Create an outline: An outline is a structure for your content that keeps you on track while writing. You can create a good outline using top-performing content, AI tools, and your expertise.
Drafting: Create a draft based on your outline and let it sit for at least two days. This gap helps you spot mistakes in your draft that you might overlook during or immediately after writing.
Submit your draft: Finally, send your draft for review to the publication. They might edit your draft or ask you to make some changes before they publish it. Some publications also use AI content detectors, so if your publication does, make sure to verify your content using the same AI detector.

While you're building your portfolio of technical articles, you can share them on LinkedIn (and other social media sites like Twitter) to let the world know about your new skills – and that you're writing about interesting technical topics.

You can also include a link to your LinkedIn profile in the articles you write, if the publication allows it, to help people find you. You'll be amazed to see how many people admire your work, and this will keep you going. You might also receive paid projects and job opportunities in your DMs.

Upskill to Documentation Writing

One great way to practice your technical writing (and help others along the way) is to contribute to documentation issues on GitHub open-source projects. This will expand your skillset and give you experience writing documentation and help you become more familiar with contributor guidelines.

Documentation writing is more focused on the product and, unlike blog posts, is usually concise. It follows a predefined structure, and the content format across pages is consistent. Accessibility, consistency, and clarity are the general best practices of writing documentation.

Pay attention to the editor's suggestions to develop a better understanding. There are usually two types of editor suggestions: objective and subjective. Objective suggestions are about general writing guidelines such as transition and clarity, whereas subjective suggestions are focused on company tone and preference.

Objective suggestions help you improve your writing skills and subjective suggestions guide you to align with company voice.

Find Paid Projects

Once you're comfortable writing technical content and doing content research, start searching for paid work. Apply to entry level jobs or look for freelance projects on job boards and in your circle. Doing the real work will really help advance your technical writing journey.

Though freelance platforms have become competitive, you can still find paid projects there. Personal branding works wonders in landing paid opportunities. Keep your GitHub and LinkedIn profiles updated, and share your achievements there to attract potential clients and stand out from the crowd.

How to Learn the Skills for Technical Writing

You can find a lot of quality writing courses, but finding the right course can be a struggle. I've taken quite a few writing courses and I'd love to help you out by sharing the tips and courses that are worth your time:

The Secret Sauce of Great Writing by Shani Raja is a perfect course for beginners. It covers the core aspects of good writing with practice exercises and lots of examples.
DevRel Uni is an online cohort-based program for people seeking to switch to developer relations. They've got a separate class on documentation writing where experts share the secrets of good documentation.
Whenever you secure your first external project, pay attention to editor suggestions. If it's a contributor article and they don't offer a one-to-one editing process, compare your submitted copy with the published article. Take notes of the changes they made. Editor suggestions are precious to make your writing better and if you take them seriously, you'll witness improvements in your writing soon.

Conclusion

Though career change can be exciting, transitioning from development to technical writing isn't too daunting. You just need to manage your career change anxiety, build a portfolio, and start cultivating your personal brand for a successful transition.

Still got questions? Feel free to reach out to me on LinkedIn.

Learn GitHub-Flavored Markdown Syntax and Formatting – With Examples

Rajdeep Singh — Thu, 11 Apr 2024 19:08:04 +0000

Markdown is a lightweight, open-source, easy-to-read and easy-to-write method of formatting text that you can use as plain text in any IDE or editor.

When writing on GitHub, you can use Markdown syntax and HTML elements to extend Markdown's functionality. You can use Markdown syntax everywhere in GitHub, such as in the README file, wiki, comments, pull requests, and when creating issues.

For every software developer, learning markdown is an essential step along the path of your career.

To enhance Markdown's basic features, GitHub added some custom functionalities and created GitHub-Flavored Markdown. With this, you can easily interact with other users in pull requests and issues by mentioning user, issue, and PR references and adding emoji.

This tutorial teaches you the basics of GitHub-Flavored Markdown so you can start using it in your projects.

All the code is available in the GitHub repository.

GitHub-Flavored Markdown Syntax

GitHub Flavored Markdown syntax is divided into two parts.

Basic Formatting Syntax
Advanced Formatting Syntax

We'll look at each one in detail below.

Basic Formatting Syntax

Basic formatting syntax applies to everyone. It contains fundamental essentials such as headings, code, images, quotes, links, and so on – things you'll need to know for writing.

Headings
Paragraphs
Comment
Styling text
Quotes
Code
Links
Images
Lists
Mentioning people and teams
Referencing issues and pull requests
Using emojis
Footnotes
Alerts

Note that the code samples mostly come from GitHub's documentation.

Headings

You can use the # symbol to create headings. One # creates an H1 heading, two create an H2 heading, and so on, like this:

# A first-level heading
## A second-level heading
### A third-level heading
#### A four-level heading
##### A five-level heading
###### A six-level heading

Paragraphs

To create paragraphs, you can use a blank line to separate one or more lines of text or paragraphs.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Etiam est odio, commodo id diam sed, pulvinar sagittis tortor. Nam vestibulum purus eros. Sed congue, mi id pretium auctor, nibh augue iaculis arcu, eu tristique quam dolor at erat.

Quisque vel odio condimentum, mollis sem vitae, porta diam. Praesent ligula elit, condimentum eget ex sed, commodo sollicitudin sapien.


Proin volutpat faucibus nulla. Nullam eros sem, ultricies gravida nunc nec, dapibus posuere nisl. Nunc lacinia elementum turpis in pharetra. Aenean eu neque eros.

Comments

Comments are available in almost every programming language. They help developers write notes and add additional information to their code, helping other developers understand what's going on and how the code is working.

To add notes and additional information in Markdown, use the following syntax: .

Here's an example:

Styling text

You can apply basic styles to your text, such as bold, italic, strikethrough, subscript, or superscript, to improve readability and convey your point more clearly.

For Bold, you can use the following syntax: **your text**
For italics, you can use the following syntax: *your text* or _your text_.
For strikethrough, you can use the following syntax: ~~your text~~
For subscript, you can use the following syntax: The subscript _text is here.
For superscript, you can use the following syntax: The superscript ^text is here.

## Bold

**your text**

## italics

*your text*
_your text_

## strikethrough

~~your text~~

## subscript

The subscript <sub> text sub> is here.

## superscript

The subscript <sup> text sup> is here.

Quotes

A blockquote or quote is a sentence or paragraph formatted to let the reader know that you're quoting someone. To create a blockquote in Markdown, you can use the > symbol.

> Text that is a quote

Code

Markdown files support two types of code samples: inline and code block.

To add a code block in a Markdown file, use the following syntax: ``` your code ``` .
To add inline code to the Markdown file, use the following syntax: `your code` .

## Code Block

// ES5 syntax var multiply = function(x, y) { return x * y; };

// ES6 arrow function var multiply = (x, y) => { return x * y; };

// Or even simpler var multiply = (x, y) => x * y;


## Inline code 

JavaScript provides three different value comparison operations: strict equality using `===`, loose equality using `==`, and the `Object.is()` method.

To support code highlighting in a code block, you can add an optional language identifier after your triple backticks (like JavaScript in the example below):

## Code Block

```javascript

// ES5 syntax
var multiply = function(x, y) {
  return x * y;
};

// ES6 arrow function
var multiply = (x, y) => { return x * y; };

// Or even simpler
var multiply = (x, y) => x * y;


### Links

A markdown file divides links into two categories: **inline** and **relative**.

#### Inline links

To create an inline link in a Markdown file, wrap the link text in brackets `[ ]` followed immediately by the URL in parentheses `( )`.

```markdown
This site was built using [GitHub Pages](https://pages.github.com/).

Relative links

Relative links are defined similarly to inline links but they change in the [] section: the [] section contains the path of the file in your repository.

You use relative links to link two files: for example, to link the CONTRIBUTING file into the README file.

[Contribution guidelines](docs/CONTRIBUTING.md)

Relative links starting with / will be relative to the repository root. You can use all relative link operands, such as ./ and ../.:

[Contribution guidelines](../docs/CONTRIBUTING.md)

Images

To add an image in a markdown file, add a ! and then wrap the alt text in []. Then, wrap the image link with parentheses ().

It looks like this:

![Markdown](https://img.shields.io/badge/markdown-%23000000.svg?style=for-the-badge&logo=markdown&logoColor=white)

Lists

A list helps record essential information in order, which can be vital for the reader and makes it easy for people to understand and find information.

Markdown files support three types of lists:

Ordered list
Unordered list
Task list

Ordered list

The first type is an ordered list. To create an ordered list, start with numbers followed by periods.

1. one
2. two
3. three
4. four

Unordered list

The second type is an unordered list. To create an unordered list, use -, + or * (depending on your preference - they'll all render as an unordered list):

* First item
* Second item
* Third item
* Fourth item


- First item
- Second item
- Third item
- Fourth item

+ First item
+ Second item
+ Third item
+ Fourth item

Task list

The third type is a task list. To create a task list, list items start with a hyphen, followed by a space, followed by square brackets []. You can use an x in the bracket [x] to mark a task as complete.

- [x] #739
- [ ] https://github.com/octo-org/octo-repo/issues/740
- [ ] Add delight to the experience when all tasks are complete :tada:

Mentioning people and teams

Mentioning users and teams in markdown

To mention a person or team in a GitHub markdown file, type @ and write the username or team username.

## person or individual username

@officialrajdeepsingh, check out the following change.

## Team or company
The section blog theme is maintained by @frontendweb

Referencing issues and pull requests

Issues and pull requests

To mention issues and pull requests in a GitHub markdown file, type a #, then type the issue or pull request number or title. Then press either tab or enter to complete the highlighted result.

Remove the default _target blank in logo #93

Using emoji

Adding emoji in markdown.

To add an emoji to your writing, type the emoji's code between two colons. If you just type :, a list of suggested emojis on GitHub will appear.

Once you find the emoji you're looking for, press Tab or Enter to choose the highlighted result.

Don't forget to leave a star on our repository! :star:

Footnotes

To add a footnote reference, add a caret and an identifier inside brackets ([^1]) using the following syntax:

Here's a simple footnote,[^1] and here's a longer one.[^bignote]

[^1]: This is the first footnote.

[^bignote]: Here's one with multiple paragraphs and code.

Alerts

Alerts are a Markdown extension based on the block quote syntax that you can use to emphasize important information.

GitHub Flavored Markdown supports five types of alerts: [!NOTE], [!TIP], [!IMPORTANT], [!WARNING], and [!CAUTION]. You can use any of them:

> [!NOTE]
> Useful information that users should know, even when skimming content.

> [!TIP]
> Helpful advice for doing things better or more easily.

> [!IMPORTANT]
> Key information users need to know to achieve their goal.

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.

The Alert syntax looks like this in the browser:

Adding alert example in markdown.

Advanced Formatting Syntax

This advanced formatting syntax section contains advanced use cases, such as adding diagrams and tables, collapsed sections, mathematical expressions, and more.

Creating a table
Creating a collapsed section
Creating diagrams
Mathematical expressions

Creating a table

To create tables in Markdown, you can use pipes | and hyphens -. Hyphens are used to create a column's header, while pipes are used to separate columns.

| First Header  | Second Header |
| ------------- | ------------- |
| Content Cell  | Content Cell  |
| Content Cell  | Content Cell  |

The table looks like this in the browser:

Table example in markdown.

Creating a collapsed section

To create a collapsed section in a markdown file, you can use the

tag. This tag is an HTML element that you can easily use to extend the functionality of GitHub Flavored Markdown. Here's how it works:

<details>
  <summary>Click to here. summary>

   ### You can add a message here

   You can add text within a collapsed section. 

   You can add an image or a code block, too.

   ```ruby
     puts "Hello World"


The collapsed syntax looks like this in the browser:

![Collapsed example in markdown.](https://www.freecodecamp.org/news/content/images/2024/04/Collapsed-in-markdown.png)
_Collapsed example in markdown._

### Creating diagrams

To add diagrams to a Markdown file, use triple backticks and wrap them inside quadruple backticks. Then, tell which identifier (Mermaid, GeoJSON, TopJSON, ASCII STL) you used for the diagram.

GitHub supports diagrams using four syntaxes: mermaid, geoJSON, topoJSON, and ASCII STL.

1. [Mermaid](#heading-mermaid) 
2. [GeoJSON and TopoJSON](#heading-geojson-and-topojson)
3. [ASCII STL](#heading-ascii-stl)

#### Mermaid 

[Mermaid](https://mermaid.js.org) is a Markdown-inspired tool that renders text into diagrams. You can create flow charts, sequence diagrams, pie charts, and more with Mermaid.

The GitHub-flavored Markdown has extended the functionality of using Mermaid with Markdown.

You can create flow charts, sequence diagrams, pie charts, and so on inside Markdown. GitHub handles the rest of that. So how do you render diagrams on the screen?

```markdown
```mermaid
graph LR;
   A --  and --> B -- to --> C


The mermaid syntax looks like this in the browser.

![Mermaid example in markdown.](https://www.freecodecamp.org/news/content/images/2024/04/mermaid-degram.png)
_Mermaid example in markdown._

#### GeoJSON and TopoJSON

You can use [GeoJSON](https://geojson.org/) or [TopoJSON](https://github.com/topojson/topojson) to add an interactive map to a GitHub repository in a README file or GitHub Wiki.

You can use code block syntax to add an interactive map.

1. GeoJSON can create a map by specifying coordinates. To add an interactive map, use the following syntax:  ` ```geojson  your code ``` `
2. TopoJSON can create a map by specifying coordinates and shapes. To add an interactive map, use the following syntax: ` ```topojson  your code ``` `

**Example using GeoJSON:**

```markdown
```geojson
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": 1,
      "properties": {
        "ID": 0
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
              [-90,35],
              [-90,30],
              [-85,30],
              [-85,35],
              [-90,35]
          ]
        ]
      }
    }
  ]
}


**Example of TopJSON:**

```markdown
```topojson
{
  "type": "Topology",
  "transform": {
    "scale": [0.0005000500050005, 0.00010001000100010001],
    "translate": [100, 0]
  },
  "objects": {
    "example": {
      "type": "GeometryCollection",
      "geometries": [
        {
          "type": "Point",
          "properties": {"prop0": "value0"},
          "coordinates": [4000, 5000]
        },
        {
          "type": "LineString",
          "properties": {"prop0": "value0", "prop1": 0},
          "arcs": [0]
        },
        {
          "type": "Polygon",
          "properties": {"prop0": "value0",
            "prop1": {"this": "that"}
          },
          "arcs": [[1]]
        }
      ]
    }
  },
  "arcs": [[[4000, 0], [1999, 9999], [2000, -9999], [2000, 9999]],[[0, 0], [0, 9999], [2000, 0], [0, -9999], [-2000, 0]]]
}


### ASCII STL

GitHub Flavored Markdown supports STL syntax. STL syntax allows you to add interactive 3D models in markdown. You can use the following syntax: ` ```stl your code.``` `

```markdown
```stl
solid cube_corner
  facet normal 0.0 -1.0 0.0
    outer loop
      vertex 0.0 0.0 0.0
      vertex 1.0 0.0 0.0
      vertex 0.0 0.0 1.0
    endloop
  endfacet
  facet normal 0.0 0.0 -1.0
    outer loop
      vertex 0.0 0.0 0.0
      vertex 0.0 1.0 0.0
      vertex 1.0 0.0 0.0
    endloop
  endfacet
  facet normal -1.0 0.0 0.0
    outer loop
      vertex 0.0 0.0 0.0
      vertex 0.0 0.0 1.0
      vertex 0.0 1.0 0.0
    endloop
  endfacet
  facet normal 0.577 0.577 0.577
    outer loop
      vertex 1.0 0.0 0.0
      vertex 0.0 1.0 0.0
      vertex 0.0 0.0 1.0
    endloop
  endfacet
endsolid


The STL syntax looks like this in the browser:

![STL example in markdown.](https://www.freecodecamp.org/news/content/images/2024/04/stl-example.png)
_STL example in markdown._

### Mathematical expressions

You can add mathematical expressions, such as equations, terms, formulas, and so on, to a GitHub markdown file. GitHub uses [LaTeX](https://www.cmor-faculty.rice.edu/~heinken/latex/symbols.pdf) formatted within Markdown. There are two ways to add these expressions:

1. Writing inline math expressions
2. Writing math expressions as code blocks

#### Writing inline math expressions

An inline math expression starts with `$` and ends with `$`. 

```markdown
Inline math expression example: $\sqrt{3x-1}+(1+x)^2$

The inline math syntax looks like this in the browser:

Inline math expression example

Writing math expressions as code blocks

To add a math expression's code block to the Markdown file, use the ```math code block and wrap it inside ``` backticks to display the expression as a block.

To add a math expression's code block to the Markdown file, use the ````math code block and wrap it inside triple backticks to display the expression as a block.

```math
\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)

```

The math code block syntax looks like this in the browser:

Code block math expression example

Conclusion

Markdown syntax works well in GitHub and all other central Git servers, such as GitLab, Gitea, and so on.

Different tools name their markdown differently. For example, GitHub extends markdown functionality in its own way and builds GitHub Flavored Markdown. GitLab also extends markdown functionality and builds and creates a GitLab-flavored markdown.

Markdown syntax is mostly the same in every Git service. But alerts, diagrams, and a few other features only work in GitHub Flavored Markdown.

Reference

GitHub docs – quickstart for writing on GitHub
GitHub docs – basic syntax
Tutorial about rendering STL in Markdown on GitHub

How to Add a Table of Contents to Your Article on Ghost

Ayu Adiati — Fri, 01 Dec 2023 19:47:28 +0000

A table of contents (or TOC) is a list of chapters or section titles in an article. You'll usually find it at the beginning of an article, right after the introduction.

When you write a long blog post or an article with independent sections, consider adding a table of contents. It can help your readers understand your article's content and know what's coming. Providing hyperlinks to each title in the table of contents helps readers navigate between the sections they want to check out.

Having a table of contents in your articles also benefits you as a writer. First, you can easily see the flow of your article. Another benefit is that it can increase your blog's traffic. If your readers have a great experience reading your article, they will likely bookmark and return to it.

Some publications use Ghost to write and publish articles on their website, and freeCodeCamp is one of them. In this article, I will walk you through how to add a clickable table of contents to your article on Ghost.

Understanding Headings
How to Add a Table of Contents
Final Words

Understanding Headings

Before we jump into how to add a table of contents, let's take a moment to understand "headings" because I will use this term going forward.

Headings are titles of sections and subsections that are displayed on a website.

There are six levels of headings based on the importance of the section.

Levels of headings – H1 - H6

Following best practices, a page on a website should only have one heading level 1 (known as h1). It is the main title of the page. In your case, it'll be the main title of your article. (In this article, it's "How to Add a Table of Contents to Your Article on Ghost".)

So, writing an article on Ghost (or any other publication platform) leaves you with h2 to h6 for your section and subsection titles. And you can use as many of them as you need depending on the hierarchy and organization of your content.

How to Add a Table of Contents

You can create your table of contents whenever you want – before you write, during the process, or after you finish writing your article.

But you can only add the link to each chapter or section title after writing your article. This is because you'll need to know exactly how the text of the headings will appear in order to link to them properly, as you'll see below.

In this guide, I'll show you how to build a ToC in HTML, which allows you to add subheadings in addition to main headings/section titles.

Step #1 - Create a List of Headings

You can create a table of contents with a list of one-level headings (h2) or include the subheadings (h3 to h6) if you want to.

You can also choose how you want to format your list:

Unordered List: A list with bullet points.
Ordered List: A list with numbers.

Create a List of One-Level Headings

Follow these steps to create a one-level headings list:

Insert a new line.
Type a dash (-) or an asterisk (*) for the unordered list. Or, type a number and add a period — for example, 1. — for the ordered list.
Hit the spacebar.
Add the title.
Click enter to add a new item in the list.

Add an unordered and an ordered list.

Note: You can skip the next section and go directly to "Step #2 - Inspect a Heading and Find the id" if you want.

Create a List with Subheadings

If you wish to create a list with subheadings (nested list), you must use HTML to format it manually, as Ghost doesn't have nested list options built into the editor.

First, you need to add the HTML card:

Start on a new line.
When your cursor is on the new line, you will see a plus (+) icon button in the circle on the left. Click this button.
Click the "HTML" option.

A plus sign and an "HTML" option on Ghost.

Afterward, you will see the HTML card, as shown in the image below.

HTML card on Ghost.

Now, let's start adding the list of your headings and subheadings.

Add an HTML unordered list (

) or an ordered list () element.

<ul>ul>

or

<ol>ol>

To add the list of your headings, add a space between the ul or ol tags. Put the cursor between the tags and hit enter twice.

<ul>

ul>

Then, add list elements (

) in the empty line between the opening and closing ul or ol tags. Add these list elements based on the number of your section titles.

<ul>
    <li>li>
    <li>li>
    <li>li>
ul>

Afterward, put each of the titles between the li tags.

<ul>
    <li>Heading 2 - Part 1li>
    <li>Heading 2 - Part 2li>
    <li>Heading 2 - Part 3li>
ul>

To add subheadings, repeat all the steps. But now, you should put the ul or ol element inside the li element(s) that hold the section title. Here's how to do it:

Place your cursor between the end of the section title and the
Click enter again to add a space and add an ul or ol element for the subheadings.
Add an ul or ol element in the new line, put the cursor between the tags, and hit enter twice to add a space.
Add li element(s) in the new line between the ul or ol tags.
Put the subsection title between the li tags.

Creating a nested list in HTML.

Below is an example of a table of contents with subheadings in HTML.

<ul>
    <li>Heading 2 - Part 1
        <ul>
            <li>Heading 3li>
            <li>Heading 3li>
        ul>
    li>
    <li>Heading 2 - Part 2
        <ul>
            <li>Heading 3
                <ul>
                    <li>Heading 4li>
                ul>
            li>
        ul>
    li>
    <li>Heading 2 - Part 3li>
ul>

And the result will look like this:

A list of section and subsection titles.

Step #2 - Inspect a Heading and Find the `id`

After creating the list, it's time to add the links to the titles in your table of contents.

But first, you need to find the id attribute of your heading using preview mode by inspecting the title with your browser's (Chrome or Firefox) developer tools.

So, let's open your preview mode:

Click the gear icon on the top right of your Ghost editor.
Click the "Preview" link beside the "Post URL" input.

The "Preview" link is in the "Post settings" on Ghost.

Now that you are in the preview mode, right-click your mouse. You will see some options. Click the "Inspect" option to open the developer tools.

"Inspect" option on Chrome.

In the developer tools, let's click the button with a box and arrow icon on the top left to select a heading element on the page and inspect it.

"Select an element in the page to inspect it" button in the developer tools on Chrome.

Hover over a title and click on it. It will highlight the element you want to inspect in the developer tools. Inside the heading element (h2 to h6), you will see an id (shown with a red line in the image below).

Inspect a heading with developer tools on Chrome.

Double-click on the value inside the quote marks of the id and copy it. You will use it to add the link to the title in the table of contents.

Note:

If you created a list of one-level headings, head to the "Add a Link to a Heading" section.
If you made a list with subheadings, go to the "Add a Link to a Heading in HTML" section.

Step #3 - Add the Link

Add a Link to a Heading

To add the link, return to your table of contents in the Ghost editor. Then, follow these steps:

Highlight the title that you want to add the link to.
Click the chain icon.
Type a hashtag (#) in the input field and paste your copied id value.

So, it will be like this:

Highlighting a list and a chain icon on Ghost.

#understanding-headings

After you refresh the preview page, check if the link works. It should take you to the target section when you click the title's link. If not, read the "Why Does the Link Not Work?" section.

Add a Link to a Heading in HTML

First, let's return to your Ghost editor and go to the li element that holds the title in the table of contents.

Then, wrap the title inside an anchor element () and add href="" attribute in the opening tag.

<ul>
    <li><a href="">Understanding Headingsa>li>
ul>

The anchor element creates a hyperlink, and the href attribute is the placeholder for the link's destination.

Now, you will add the link's destination. Type a hashtag (#) and paste the id value you've copied inside the double quotes of the href.

<ul>
    <li><a href="#understanding-headings">Understanding Headingsa>li>
ul>

Repeat all the steps to add a link for each title.

Below is an example of section and subsection titles with links in HTML:

<ul>
    <li><a href="#understanding-headings">Understanding Headingsa>li>
    <li><a href="#adding-a-table-of-content">Adding a Table of Contenta>
        <ul>
            <li><a href="#step-1-create-a-list-of-titles">Step #1 - Create a List of Titlesa>li>
        ul>
    li>
ul>

After refreshing the preview page, you can now check if the link works by clicking it. If it doesn't work, read the next section.

Why Does the Link Not Work?

If you click a link in your table of contents and it goes nowhere or redirects you to a "404 Page not found", return to the preview page. Refresh it, and try to click the link again.

If it still does the same, you need to check the link in the Ghost editor.

Sometimes, it can be a typo where you change the title but still need to update the link. Or there is a missing hashtag (#) in the link.

Final Words

If you liked and found this article helpful, please share it with others. You can find other works on my blog. Let's connect on X (formerly Twitter) or LinkedIn.

Technical Writing for Developers – Why You Should Have a Blog and How to Start One

Ankur Tyagi — Mon, 23 Oct 2023 17:22:04 +0000

Having a blog is a useful asset for developers. It can be a lead magnet, as well as a place where you can sell digital products you create.

It can also simply be the place where you build a loyal audience within your niche, share your knowledge and ideas, and help other devs.

The benefits of having a personal blog as a developer

In this article, I'll share why I blog, as well as why I think it's a great idea for you, too.

Why I Write Technical Articles

Here's something I've learned over the past five years of blogging: don't start by telling the audience why you wrote a blog post. Instead, tell them why they should read it, and then do your best to prove yourself right.

I recently revamped my blog and began writing consistently, to the point where I now write a new tutorial once a week. And I’ve already seen a lot of good results.

I've also started paying more attention to my analytics. This helps me give people what they want, answer their questions, and keep them coming back for more. I'll talk a bit more about analytics later.

I found my mission in teaching developers about topics like how to start your own blog, how tools such as React, Angular, JavaScript, and TypeScript work, and so on. I release a new article every week on my blog theankurtyagi.com, explaining all I know about a specific topic.

If you are into React or developing on the Web, you won't want to miss it. And I just started creating a new React writing boot camp where I share my 14 years of tech experience and how I've built multiple applications.

Now I'll share my thoughts on writing technical tutorials, and why I think you should have your own blog as a developer.

Understand Your Tech Abilities and Soft Skills

If you’re working in tech, you can take advantage of the skills you already have and share your knowledge with the community. Do any of the following statements apply to you?

You excelled at much of your past work, and you know that companies (or people) will pay for that work.
People ask you for advice based on your past work.
Somebody said, “You should write something or record a video to document your experiences because you offered me so much value when you mentored me or helped me in a peer programming session or saved me from that production bug while reviewing my PR pull request”

The value you bring to your audience comes from a combination of your perspective and your interpersonal skills.

Think back to what other people have asked you to do, or what you've volunteered to do in your career—because you're good at those activities.

But don’t stop with technical skills. While core technical skills are useful, they are not all you'll need for long-term success as you move up in your tech career. That’s because the more responsibility you take for your client’s growth and results, the more the more helpful you can be to other people’s work. And this often starts with communication skills – so don't neglect them.

Doubts You May Have Before Starting a Developer Blog

I am not an expert writer

Every developer has a unique angle and a perspective on something worth sharing.

You may believe you don't know as much as senior developer X, but junior developer Y may have much less experience and would benefit from reading about your career journey and learnings.

Also, the best time to teach something is right after you've learned it because you remember how it feels when you didn't know it – so you can more effectively teach a beginner about it.

In this case, you can write for a student who has recently learned something new. Every day, I learn something new.

Approximately 80% of what I end up writing these days is something I discovered while researching a topic on the internet.

I’m just a good enough writer

I'm not a professional writer, but that doesn't bother me. Remember that you will never become a better writer unless you write every day for years. If you practice enough, and actively try to improve your writing, you'll eventually improve your writing skills.

To create something good, just start writing. To create something exceptional, write, revise, and revise again. The key to producing excellent writing lies in dedicating significant time and effort to the rewriting process.

All Developers Fear Criticism

Some things are fragile and break with a sudden shock, like a water glass.

Some things are not fragile and remain intact even when faced with a sudden impact or shock, like a teddy bear.

And some things, like our immune system, are anti-fragile, meaning they improve when subjected to a shock. Your immune system does not develop properly if you are not exposed to a series of smaller shocks as a child.

Similarly, to become a better developer in tech as a result of criticism, you must develop an anti-fragile attitude towards criticism. That is, with every bit of critique you receive, you can learn to use it to become better.

If you do not learn this, you will remain at your current level. You can do this at the meta-level as well: become anti-fragile in dealing with criticism in general, and become a better human being as a result of it.

Empowering self-hacking starts with cultivating a heightened awareness of your own emotional state. Recognizing anger, for instance, weakens its hold on you. When angry, you may engage in actions you otherwise wouldn't. (Anger can sometimes serve as a signal that our boundaries have been crossed.)

Certain online platforms, like Reddit and Hacker News, are known for their unfiltered feedback. Embrace this as an opportunity for growth. Remember, you only truly evolve when faced with challenges.

You also have the choice not to engage if you prefer. Concerned about potential negative comments on a controversial post? You can always disable comments altogether.

Also, remember that not everyone gives valuable criticism in tech.

Some people just don’t connect with your work.
Some people won’t like what you’re writing.
Some people aren't yet ready to critique your work.
Some people are just mean.
Some people like your style of writing. Others won't.

And sometimes when people stare at screens all day, like those of us in tech, they can unwittingly be more harsh and direct. It's not a great way to communicate, but it might not be malicious.

If you can get past the sting of the critiques and use them to improve your writing, you'll have a lot to offer the developer community through your tutorials.

How to Start Writing Your Own Blog

Rich people might seem to have it all – money, power, influence, and whatever else they crave. But there’s one thing they want that money can’t buy: good ideas.

Writing is how you share your ideas, and if you do it well, you can often gain access to a coffee or dinner with almost any tech CEO in software engineering.

I've been writing for around 5 years, so here's my take:

Just start writing: If you've been wanting to start your own blog, stop thinking about it, and just do it. Open a blog on WordPress and start writing. That's my first advice to anyone. Don't waste time on the technicalities, just write. You can move your blog to another platform later.
Be consistent: This is hard. I fail to follow this rule most of the time. But a successful blog is a blog that's been going on for ages, and where the creator posts regularly. I've posted 100+ posts since 2020 on my blog and 100+ for various startup developer tools – and that's why it has been working well for me.
Don't try to be perfect: You are not writing a book. A blog is to share knowledge quickly or to share what's on your mind. No hesitation, once you have something, publish it. People might call you out for saying something wrong, fine – that's free publicity and you'll have learned something new.
Mix short posts with long posts: It's difficult to keep writing high-quality content and long blog posts all the time. So write small ones from time to time to fill in between more in-depth guides. This is what makes people keep going to your blog. It's like a Twitter feed, it needs to have something every time people check it.
Write on current/popular subjects: What did you learn recently that could be helpful to other people? What did you have trouble learning because there was no good resource on the subject? You could be that resource. What is Google Trends saying? Are there any trendy topics in your field? What are people talking about recently?

I generally start with an idea instead of a title. Then I write down what I know about it. Next, I put those thoughts in an order that I can use to tell a story. Finally, I research to confirm that what I think I know is indeed true and correct. That is where it becomes interesting.

Sometimes I'm completely wrong, and the story becomes about that. The truth is often more interesting than the assumptions.

Sometimes I discover things about what I knew that are more interesting than the original idea. Sometimes what I thought I knew turns out to be true and I just back it up with facts and the idea alone was interesting enough to begin with.

And lastly, sometimes the idea is actually not worth sharing, and I shelve it until the time feels right or I find a new approach to the subject.

Why Writing is Helpful for Developers

You learn much faster

Writing is a great skill for a developer for many reasons, including:

You learn by doing.
You learn faster.
You build a lot of connections which can generate future leads and opportunities.
You can work on different tech stacks
It’s a great form of self-expression.
It encourages creativity.
It helps to connect with your imagination.

I enjoy writing because it forces me to read more. And as a result, I learn a lot and stay sharp while working and collaborating with others.

One of the best ways for me to learn is by doing. I pick a topic about which I believe I know something and drill down through things I didn't know or hadn't even considered.

My best tip for anyone willing to start a blog: Read, read, read, write, write, write, read, read, write, write, write, write, read, read, read, read, write, write, write, edit, edit, edit, edit, edit, edit, edit, read, read, read, write again.

They say you never fully understand a topic until you can explain it.

And blogging is often low-hanging fruit.

Every developer should make a habit of blogging about their learnings in software engineering. Writing helps you discover if you understand a topic as well as you think you do.

Teaching and writing are great ways to learn, and they're good habits to start because you already have firsthand experience. Just commit to writing 12 blog posts a year, see what happens, and plan your next steps based on that.

As David Perell says, “Read to collect the dots, write to connect them.”

How writing is a low hanging fruit for experienced developers

Writing involves critical thinking

So many things never fully connected for me until I wrote about them. And so many other things I thought I understood well in my head turned out to be half-baked when I start writing about them.

My blog "A Software Developer's Guide to Writing" is a complete guide on how to start a blog.

Writing is a form of self-expression that can be therapeutic, even if you never intend to publish your work.

How Writing Can Help Advance Your Software Engineering Career

I’ve elevated my career in software engineering thanks to my writing.

It was 2017, and I'd begun writing about small things I was learning while building a few web applications for fun as a side project. I'd also gotten the opportunity to contribute to internal developer docs in my previous job as a tech lead.

That old blog has since died — I stopped writing on it a long time ago, and the content, which is now completely obsolete, has vanished. But I doubt I could have imagined starting my current small writing business without it.

Through my current blog, I have a lot of connections and opportunities for freelance gigs and part-time roles. It's also helped me in my consulting career.

Writing tutorials can help you learn a new tech stack

Writing helps in learning a new technology stack this is something I've done a few times with my writing. If I am interested in one type of technology stack and then become interested in another, I will write several posts about it.

For example, last summer I wrote about multiple developer tools in this article: How to Create a Powerful Next.js E-commerce Store.

How to build an e-commerce store with Medusa a blog by Ankur Tyagi

Other benefits of technical writing

Writing about technical topics is a great way for you to show what you know and what you're able to do. It can also help build your authority in tech by establishing your reputation and building your personal brand.

It can also improve your opportunities for networking and career advancement, as more people read your tutorials. And the more you write, the better your communication and collaboration skills will become.

Another benefit I discovered from sharing my writing publicly is that it caught the attention of many company founders, who then offered me writing jobs. They found me through my blog posts online, even though I hadn’t applied to work with them. Take a look at the below inbound cold email I received.

An inbound cold email from a tech founder

So having a blog is an effective way to demonstrate that you are passionate, know your stuff, and can communicate effectively in writing. The simplest way to begin is to write posts about topics that have interested you or problems you've solved.

How to Write an Effective Technical Blog

Keep your topics consistent

I only follow blogs that have a clear focus or theme.

In my case, I talk about Web Development, React, Developer Tools, and so on, and I subscribe and consistently read other developers' blogs that are focused on a particular area of tech.

Don't just rant about anything that comes to mind. Use a professional tone and cultivate your own unique writing style.

Setup a routine

If you aim to write a blog post weekly, make sure you follow through. Writing two posts a week is even more ideal. I write every day because I know that if I skip one day, I will skip another, and so on until I stop posting altogether.

Write blog posts in advance

Don't post the same day you write. Instead, schedule your content for a week later and review it the day before.

This is a big deal. By waiting a week before you post and looking at it again, the quality of your content will improve. A lot!

Write it a week or more in advance. Even if you take a few days off or are sick, you are less likely to miss a blog post day. It's also a good idea to make your posts public ahead of time. WordPress makes it very simple, and it is also possible to schedule a specific time and day to write on a consistent basis.

If you write down 5 ideas per day, that will amount to 1,825 ideas in a year (assuming it's not a leap year). Among these ideas, you're likely to find a few outstanding topics for your blog posts. Try to maintain a roster of potential blog post ideas. When inspiration strikes, you'll find the perfect topic for that day in your backlog.

In your articles, take things a step further and make your content 10x better by telling your audience the "why" of things. This is much harder to do.

If your writing is poor quality or inconsistent, you'll end up with the wrong audience. Write with intention and purpose. Write to become better. Instead of writing more, start editing more.

Build your writing, not your website

You can use big blogging platforms to increase your visibility. Think long-term. In the next ten years, every blog post you write could be worth thousands of views.

When a developer comes to me and says, "Hi Ankur, I'm a developer and want to start a blog. What should I do?", here are the two options I discuss with them:

Option 1: start publishing your articles on an established blogging platform

Option one is starting with a platform like Medium, Hashnode, DevTo, HackerNoon, or Dzone.

You can start writing articles and publishing them on one of thoes platforms, and work on building your credibility as a writer. Set a goal for yourself – for example, try to get to 100K+ post views/year.

Then you can start learning about and implementing SEO strategies, especially if you start writing on your own blog.

One potential challenge with this approach is that you may not technically own the content you publish on other's sites (check their rules). The company could even go out of business or shut down their service, and you may lose all your articles.

So here's my advice on how to handle this: if you stick with writing for a year, then it's time to start moving slowly onto your own website and posting your articles there.

Another challenge is that you don't necessarily want to spend all your time building a personal blog and just have one post titled "How I made this beautiful blog with X framework" to show for it. Instead, you could've had dozens of blog posts on rented spaces (like Medium, Hashnode, DevTo). Build your brand before building a house.

You can treat Medium, Hashnode, Twitter, and other platforms as traffic-acquisition channels rather than a home for your long-form content. Because no moderator can delete your blog posts from your own website.

Option 2: create your own blog site from scratch

Option two involves starting with your own blog website from the beginning. You can either build your own or use something like Ghost/WordPress/ any CMS of your choice. Then you can syndicate your articles to existing blogging platforms until enough people learn about your own blog. After that, you can stop syndicating content if you want.

But I'd advise you to write 2-3 blog posts every month for a year before you even think about building your own fancy, tech-savvy website and publishing there.

Treat every blog post as a mini side project and see how it feels. If, after a year, you find you're still enjoying writing, then continue doing it. If not, blogging may not be for you.

One challenge with this second approach (building your own blog and starting there) is that many developers with full-time jobs find it hard to spare time and energy, even though they want to write. So I think it's better to start small – and maybe share your posts on an existing platform at first – to avoid this common pitfall.

Again, it's better to focus on building your personal brand and your reputation as a writer first, before investing time in creating a dedicated website.

While it can be harder to reach a large audience on your own personal blog, you have to start somewhere.

Another challenge with this approach is the tendency to over-engineer a simple static blog website, and spending too much time perfecting that site instead of writing.

When I was starting a blog, I actually got caught up in it all – but one of my friends guided me through the process and showed me WordPress, which was a lifesaver. In the case of your blog, people are often interested more in your storytelling than your actual blog website.

In my opinion, in the end, being the owner of your own blog space >>> always using rental space. Just make sure you prioritize your tasks and focus along the way.

If you're curious about my blog post writing style, I invite you to check out this post: How I Write My Blog Posts.

Building an audience

This is related to the previous point. If you're just getting started, you might get 1 or 10 or 100 visitors per week if you share your posts (unless you go viral on a sharing platform like Reddit, Hacker News, or Twitter).

Search engines like Google can often provide consistent traffic (SEO), but this is a very long game to play. It's easy to get discouraged if you write but no one reads your blog posts.

The initial years of writing can be tough and boring. Despite very good writing, your blog will likely grow slowly. Big views may seem to be a distant dream. The effects of writing kick off only after a certain amount of time when your blog may start to build up momentum. Patience and persistence are key.

So, actively look for an audience. Write on your blog and republish your blog posts to Medium, Hashnode, DevTo, and Hackernoon (remember to add a canonical tag back to your site so that you don't annoy Google with duplicate content). Having an audience will boost your enthusiasm and determination.

Promote your content

When you hit the “publish,” button you’ve only done 50% of the work.

You had an idea
You’ve done writing along with researching the topic
You’ve looked for typos and fixed grammar errors
You made sure to have no plagiarism

Now it's time to promote your writing.

Post on Twitter/LinkedIn if you have a following, otherwise try to share on HN, Reddit, and so on.

Here's what Arnold Schwarzenegger said about why marketing your product is equally as important as making the product:

Whenever I finished filming a movie, I felt my job was only half done. Every film had to be nurtured in the marketplace. You can have the greatest movie in the world, but if you don’t get it out there, if people don’t know about it, you have nothing. It’s the same with poetry, with painting, with writing, with inventions.

It always blew my mind that some of the greatest artists, from Michelangelo to van Gogh, never sold much because they didn’t know how. They had to rely on some schmuck (some agent or manager or gallery owner) to do it for them. Picasso would go into a restaurant and do a drawing or paint a plate for a meal. Now you go to these restaurants in Madrid, and the Picassos are hanging on the walls, worth millions of dollars.

That wasn’t going to happen to my movies.

Same with bodybuilding, same with politics—no matter what I did in life, I was aware that you had to sell it.

As Ted Turner said, “Early to bed, early to rise, work like hell, and advertise.”

In a similar way, whenever I finished writing a blog, I felt my job was half done.

I wanted every article to be distributed across multiple platforms. You can write the best blog in the world, but if you don't get it out there and people aren't aware of it, you're out of luck. It's the same with a book, a course, a community, a product, a startup, and your writing.

Marketing boils down to caring: Don’t confuse the word “marketing” with advertising, announcing, spamming, or giving away branded crap. Really, “marketing” just means being considerate. Marketing means making it easy for people to notice you, relate to you, remember you, and tell their friends about you. –Derek Sivers | @sivers

Your blog is your media platform

Don’t just think of it as a blog. See it as a startup: the goal of a blog is to disseminate information that drives sales and future opportunities.

Sales may make you uncomfortable, but think of it as selling ideas or your own expertise.

A big Social media following is a business card, but a big email list gives you longevity.

In reality, you don't have full ownership of your Twitter, LinkedIn, or Medium following. Your true ownership lies in your email list. I recommend SubStack; it's user-friendly, free, and exceptional.

A blog should be professional, not personal

Your audience isn't primarily interested in you. They visit your blog in anticipation of problem-solving (if they arrived from a Google search) or seeking valuable information to aid them in specific tasks. Write with their needs at the forefront to be truly helpful.

Don't use ads at the beginning

Don’t put ads on your blog. I don't think it's worth it unless you have 10,000+ visitors a day.

Watch your analytics and use them to guide you

Peter Drucker said, "You can't manage what you can't measure."

If building an audience was a piece of cake, everyone would do it. Here are my tips on how to use your analytics to improve your blog and the content you create:

Find Out What People Like to Read: Look at the pages that get the most visits. What are they about? This is what your audience loves the most. Write more about those topics.

Understand How People Find You on Internet: Examine the search terms that lead people to your site. This tells you what they're interested in and what questions they have. Answer those questions in your writing.

Know What Keeps Them Reading: See which pages keep people on your site the longest. This is the content that really grabs them. Use that style or topic as a model for your other posts.

Learn From the Bounces: On the flip side, see which pages have the highest bounce rate. These are the ones that might need a bit of tweaking.

Ask yourself, "Why are people leaving?" and then make changes accordingly.

My blog's analytics

Read books, Blog posts, Twitter, Reddit, and HackerNews

Keep yourself up to date on the topics you want to write about. I write about software engineering, and Twitter is a never-ending source of topic ideas. The same is true for books and blogs. freeCodeCamp is also fantastic for this.

Every day, I spend 1-2 hours scrolling Twitter for inspiration. It's not a waste of time. It's the catalyst my brain requires to see things I would never have seen in offline life. Luck is not as random as you think. Before a lottery ticket can win a jackpot, someone has to buy it.

My daily screen time

Wake up early if possible

Set your alarm clock, get up, and begin writing. I used to get up at 7 a.m. because I haven't had to commute since 2020 (I only work remotely), so I could take it easy. I now get up at 5 a.m. and have a new post scheduled for the following week by 7 a.m.

When you finish a task, such as writing a new blog post, by 7 a.m., you feel energised to tackle the rest of the day. If you can, get up even earlier (I can't, or I'll spend the rest of the day in a zombie state).

Start using DND (Don't Disturb) Mode

It's all too easy to become distracted while researching for a blog post on the internet. I've turned off all notifications on my phone. Writing, like programming, is best done without interruptions so that the task at hand can occupy your entire consciousness.

My advice is to set aside dedicated time on your calendar, disable notifications, set your phone aside, and commit to your keyboard or typewriter, pen and paper, or whatever.

These are the only notifications which are "ON" on my mobile:

###

Thanks for Reading!

That's it for this tutorial. I hope you learned something new today.

If you did, please share so that it reaches others as well.

You can connect with me on Twitter.

Want to read more interesting blog posts?

You can read more tutorials like this one on my personal blog here.

Introducing freeCodeCamp Press – Free Books for Developers

Abigail Rennemeyer — Wed, 30 Aug 2023 16:49:54 +0000

The freeCodeCamp community has published more than 10,000 tutorials on our publication over the years. But lately we've focused on creating even longer resources for learning math, programming, and computer science.

This is why we've created freeCodeCamp Press – a division of freeCodeCamp where we publish full-length books and handbooks on our online publication – all available to everyone for free.

What is freeCodeCamp Press?

The freeCodeCamp community publication publishes technical tutorials in many forms. We publish shorter, more focused guides that aim to answer a specific question. We also publish longer walkthroughs that help you build a specific project.

And now we're publishing more comprehensive books and handbooks that will teach you everything you need to know to get started with a certain programming language or tool.

We're going to publish a lot more of these 5,000+ word handbooks and full-length books of 40,000 words or longer.

When an author submits a substantial tutorial that we consider to be a book or handbook, the editorial team reviews and edits it as usual. This helps make sure it's as complete and polished as possible.

We've also started designing cover images for our books and handbooks. If the author wants to take advantage of this professional cover and the consistent look it gives their handbook or book, one of our team members (Estefania) designs and creates it. These covers look something like this:

Example handbook cover (freeCodeCamp Press)

After showing the proof to the author, we add the cover to the book or handbook and publish it. These covers help create a consistent look and feel for these substantial resources and make them easy to recognize.

I Want to Write a Book or Handbook for freeCodeCamp. How Do I Do That?

If you're already a contributor to the publication, and you'd like to write a longer-form book or handbook, that's great! Pick a topic you know a lot about and start writing.

You can look at some of our other books and handbooks in the next section to get an idea what these books are like, and how they're structured.

It's a serious endeavor to write a book or a handbook, so take your time. Do your research, test your code, and create something great.

If you haven't applied to become a contributor to the publication yet, but think you and your books would be a good fit, you can read our style guide here. Then, if it looks like your style is similar to freeCodeCamp's, go ahead and apply.

freeCodeCamp's Published Books and Handbooks

Here are some of the handbooks freeCodeCamp Press has published so far on our community publication. We're publishing more almost every week, so this is just a sample:

And here are some of our books:

We're just getting started publishing free books and handbooks for the developer community. And they're all accessible for free right on freeCodeCamp News.

We hope you enjoy these open learning resources, and that they help you level up your coding skills.

How I Got Accepted as an Author at freeCodeCamp

Zaira Hira — Tue, 01 Aug 2023 21:30:58 +0000

Life is full of surprises. Certain actions may lead to a chain of events and you find yourself in a completely different state.

One of my biggest achievements in 2021 was to get accepted as an author at freeCodeCamp.

I have been writing articles on freeCodeCamp's community publication since September 2021 and have published 31 articles. I write mostly on Linux and occasionally on Python and Git. You can check out my author profile here.

I have always enjoyed writing. I used to casually write stories or simply journaled about how my day went. But I never made any of my writings public.

I had been working as an application support admin for a few years. I learned a lot of interesting things during my routine work, and I loved making notes for myself.

I started to share them with my colleagues too, and realized they actually found them useful. I also noticed that people usually run away from documentation. But the drawback is that you may forget things very easily if the tech is complicated and there is a lot going on.

How I Discovered freeCodeCamp

It was a routine day at work when I was scrolling through LinkedIn. I saw that one of my colleagues had recently completed the Responsive Design Course on freeCodeCamp and had shared his certificate there. I congratulated him.

At the same time, I got curious about what freeCodeCamp was. At that time, I was also looking to polish my development skills.

I searched for freeCodeCamp online and followed them on Twitter. I had recently started using Twitter for learning about tech. Over there I saw that people were writing articles which freeCodeCamp was regularly sharing.

I explored some of the author profiles and the popular topics. I had always thought that in order to write a blog online, you had to be famous and have a huge social following. I also believed that the topic should be very complex and should be written about by an expert with years and years of experience.

I got even more curious and approached Abbey on Twitter. I asked how I could join as an author. That was the turning point.

She sent me the publication guide, and I read it a couple of times. Then I decided to apply. There was a Google form with some questions. I shared some of my sample articles that I luckily had. At that time, I was writing as a guest author for a YouTuber's blog.

But...some time went by. I couldn't get a response.👀 To be honest, I was anxious.

I was eagerly waiting for an answer. Just before I was about to give up, I decided to check my spam folder. And there it was – the email that I had been waiting for!

Tips to Help You Get Accepted

If you are keen about writing and showing it to the world, you should definitely apply for freeCodeCamp's author program. Here are some tips to strengthen your application.

Have three writing samples ready – and show your best samples. You can publish some of your sample articles on open publishing platforms like Hashnode and Dev.to to get practice writing technical tutorials before applying to freeCodeCamp.
Don't think that you have to be an expert in every topic or you need to be a tech influencer to apply. Just make sure you do your research and present the information clearly with the primary goal of educating your readers.
There is no harm in applying again with better samples if you didn't qualify the first time. Your application would still be reviewed – just email Abbey or message her on Twitter to give her a heads up.

Also, keep in mind that quality is always better than quantity. Here's a few additional tips related to that.

Plagiarism is never acceptable. So don't think you can get away with it. 👮‍♂️ If you're not sure what constitutes plagiarism, read up on it before you apply. If you think some of your articles contain plagiarism, write some more that don't. It's better for you, and everyone.
Be careful with using GPT. You can use it to assist you – help you create outlines, code samples (which you should test to make sure they work/run), and so on – and not to write the whole article for you. After all, your unique writing style is what makes you stand out. It's worth the extra time, plus you'll learn a whole lot more.

What Did I Get in Return as an Author?

The short answer is – meaningful connections!

The freeCodeCamp community is huge and powerful. I got many follows on my socials being on Twitter and LinkedIn (as freeCodeCamp shares many of the articles they publish on social media).

In the past 12 months, my articles have reached 1,904,450 people! I wasn't expecting to reach so many people when I was starting out.

I have also received appreciation from some of the kind readers. Some of my articles have also been featured in Quincy's weekly newsletter.

Wrapping up

If you have something you would like to share with the developer community, I would highly suggest you start writing. Whether you publish on your own blog, an open publishing site, or you apply and are accepted to freeCodeCamp's publication – I believe you'll see the benefits. You will also meet many great people along the way. 🤗

BTW, I would be happy to connect with you on any of these platforms. 📧

Happy coding :D

How to Improve Your Technical Writing Skills by Contributing to Open Source Projects

Christine Belzie — Mon, 12 Jun 2023 18:15:16 +0000

Have you been writing your tech blog posts on Hashnode or Dev.to, but you're itching to try something new? If so, there is something that can quench your thirst: contributing to open source.

I know, I know, you’ve probably heard “Contribute to open source!” countless times in Discord groups and tech-related social media posts. But trust me, it really can be a great way to gain experience as a technical writer.

For one, you get to work on projects that are often displayed publicly. This can be a great way to showcase your skills to your professional network.

Also, contrary to popular belief, code is not the only way you can contribute to open source projects. You can use your writing skills to help maintainers improve their projects' documentation.

And contributing to open source exposes you to new technical languages and software, which the Bureau of Labor Statistics describes as one of the many important skills in tech writers.

Still not convinced? No worries – in this guide, I will discuss how you can find open source projects that need tech writers. I'll also describe what tech writing-related contributions to these projects might look like, and suggest how to display them publicly.

How to Identify Open Source Projects That Need Technical Writing Contributions

Many open source projects need help with their documentation. Picking a project to make docs-based contributions to will be based heavily on your interests, the level of writing skills you have, and the opportunities available.

When it comes to finding open source projects that need contributions, I highly recommend asking your colleagues about the projects they are involved in. Working with friends + open source? It's two for the price one! :) Once you've picked your project, my next tip is to do the following:

Go to the Issues tab on the project's repository.

Yellow Arrow pointing to Issues tab

Click on the Label section

Orange arrow pointing at the Label section

Type "documentation" in the textbox and voilà!

"documentation" appearing in the textbox

Now if you are looking for something more specific, here is my list of open source projects with a focus on documentation:

The Good Docs Project

If you’re looking to start gaining experience in working with documentation, I highly recommend joining this group. :) They have diverse working groups that focus on different types of writing whether it’s creating documentation templates that other developers can use in their own open source projects, improving the content on the organization's website, and doing QA (Quality Assurance) for the templates that community members have created.

Codecademy

If you’re knowledgeable about a particular programming language and want to share that knowledge with the world, then I highly recommend contributing to Codecademy's docs and article repositories. They provide templates based on different needs such as providing a new entry for a certain chapter and updating/editing an existing entry.

Astro

If you’re an avid user of Astro, then you can share your tips on using this software on their docs repo. Their documentation team is very open to working with members with different levels of experience.

Now picking a project is just one step. Let's look at some different ways you can contribute to open source projects as a technical writer.

Ways to Contribute to Open Source as a Technical Writer

Congrats! You've picked your project. Now, you just have to decide how you will use your tech writing skills to contribute.

I know this part can be difficult but don’t fret – now we're going to discuss some different types of contributions you can make.

Revise typos and other grammar errors on the README file

This file is crucial to the foundation of an open source project. It's where they describe the project’s purpose and the steps to contribute to it, so it should be as clearly written as possible.

If you're reading through the README file and you see a comma missing or an unclear sentence, raise an issue about it to maintainers and make those edits (if they approve, of course).

I made this contribution to EddieHub when I first joined their community. It was not only a great way to introduce myself, but it also taught me how to tailor documentation to a specific audience. Now this not the only text-based contribution, let's look at another one! :)

Create an internal docs style guide

This entails creating a guide that defines the standards for writing and formatting the documentation for an open source project. It helps instruct contributors on how to effectively write for open source.

In this document, you'll see information such as how punctuation marks should and should not be written, specific ways to format code blocks, and the tone and voice that contributors should use when writing about the product.

A great example of this would be the Contractions section in Google's Developer Documentation style.

Also, I decided to make a doc style guide for EddieHub's Linkfree project after watching a video by Portia from Document Write's YouTube channel. She talked about how open source contributors, especially those who want to pursue tech writing as a career, can benefit from having these sorts of style guides.

Through creating this guide, I've learned the following:

Writing in a new style or language: Since Linkfree's main demographic is in the U.K., the maintainers wanted the guide to be written in British English. I've never used this version of English before, so it was interesting to learn how words are spelled, capitalized, and what punctuation marks are used.
Using new tech tools or frameworks: MDX (Markdown X) is the technical language contributors use to maintain Linkfree's documentation. Simply put, it's Markdown that allows to you to put JSX (syntax that let's you put HTML code in JavaScript). I've briefly worked with Markdown, so it was a bit easier to implement this language in creating the docs guide.

Now, a style guide is only one of the many docs-based contributions you can do for an open source project. Let's look at another one! :)

Add to a tutorial for a product

If you're good at teaching or find yourself reading an open source software's tutorial that is missing key information, consider doing this as your contribution.

A great example of this would be the tutorial section on Audacity's website. It's a free open source audio recording and editing software.

As a person who's newer to the open source community, I noticed that most beginner-level content never really provided tips or advice on how contributors can implement their open source contribution experiences when looking for jobs or during interviews. So I was scrolling through OpenSauced's repository on GitHub and noticed that this kind of content would be helpful in their free "Intro to Open Source" course.

I presented my idea to Bekah, the company's User Experience Lead, created a pull request, and violà, it got merged!

I highly recommend making this kind of contribution because a great way to gain practice is by simplifying technical content for a global audience of all skill levels. It also develops your detail-oriented skills.

Now, before you go, there’s just one more thing to consider when gaining tech writing experience through contributing to open source projects.

Show Your Work

When it comes to the importance of displaying your creations, Austin Kielon said it best: “Show your work”.

I mean, we’re writers for crying out loud! It’s in our DNA to display content through words, so why not do it with our own stuff?

You can write about your projects via your blog, social media posts, or record a podcast episode about it.

If you’re looking for something more structured, I recommend using OpenSauced's free Chrome extension. It’s a tool that allows you to keep track of the GitHub open source repositories you currently contribute to and those you plan to contribute to.

They also have this feature called “Highlights” where you can pick certain contributions to post to your profile and share on LinkedIn and Twitter. To learn how, check out their tutorial.

This would be a great thing to reference during your job interviews and it can be an inspiration for other open source contributors. When I showcased the docs style guide I created for Linkfree on Twitter, one of my colleagues liked it so much that she thought it'd be good to have one for her project. So per her request, I created one! :) Never underestimate the power of displaying your work.

There you have it folks, your guide to gaining writing experience through contributing to open source projects. I know it can be intimidating to do – especially at first – but with these tips and a positive attitude, I know you’ll succeed.

Credits

Open Source Symbol from UXwing

Tech Writing Icon by Ylivdesign from Dreamstime

Smart Quotes – Single Quote and Double Quotation Mark for Copy + Paste

Kolade Chris — Wed, 10 May 2023 14:31:24 +0000

Smart quotes are commonly used punctuation marks in HTML and in writing. Knowing how to use them correctly can make a significant difference in the clarity and professionalism of your writing.

So in this article, you will get access to the commonly used quotation marks out there that you can copy and paste them into your articles, papers, and HTML.

It doesn’t end there. You will get access to the Unicode characters, HTML entities, and CSS entities of all the smart quotes. Make sure you check the end of this article so you can learn how to use the HTML and CSS entities and Unicode characters of the smart quotes.

Before showing you a table containing all the smart quotes, let's see how to use them in HTML and CSS first.

What We'll Cover

How to Use Smart Quotes (Quotation Marks) in HTML and CSS
Table of Smart Quotes, their Unicode Characters, HTML, and CSS Codes
Conclusion

How to Use Smart Quotes (Quotation Marks) in HTML and CSS

To use smart quotes in HTML and CSS, you need their Unicode characters. For instance, the Unicode for quotation marks is U+0022. So, to use it in HTML, strip out the U+ part, prepend the other letters or numbers with &#x, and end them with semicolon (;) like this:

&#x0022;

That translates to this: "

In CSS, you need to strip out the U+ part again and replace them with a backslash (\). So this is how you'd use a quotation mark in CSS:

\0022

But there's a caveat to using Unicode characters in CSS. To make them visible on a web page, you need to create a pseudo-element and make the Unicode character the content:

element::after {
  content: '\0022';
}

Table of Smart Quotes, their Unicode Characters, HTML, and CSS Codes

The table below contains the quotation marks available for use in HTML and other writings:

Quotation Mark Name	Symbol	Unicode	HTML Code	CSS Code
Quotation Mark	`"`	`U+0022`	`"`	`\0022`
Single High Reversed Quotation Mark	`‛`	`U+201B`	`‛`	`\201B`
Double High Reversed Quotation Mark	`‟`	`U+201F`	`‟`	`\201F`
Full Width Quotation Mark	`＂`	`U+FF02`	`＂`	`\FF02`
Right Single Quotation Mark	`’`	`U+2019`	`’`	`\2019`
Left Single Quotation Mark	`‘`	`U+2018`	`‘`	`\2018`
Single Low Quotation Mark	`‚`	`U+201A`	`‚`	`\201A`
Double Prime Quotation Mark	`〞`	`U+301E`	`〞`	`\301E`
Reversed Double Prime Quotation Mark	`〝`	`U+301D`	`〝`	\301D
Low Double Prime Quotation Mark	`〟`	`U+301F`	`〟`	`\301F`
Right Double Quotation Mark	`”`	`U+201D`	`”`	`\201D`
Left Double Quotation Mark	`“`	`U+201C`	`“`	`\201C`
Double Low Quotation Mark	`„`	`U+201E`	`„`	`\201E`
Double Low Reversed Quotation Mark	`⹂`	`U+2E42`	`⹂`	`\2E42`
Heavy Right Pointing Angle Quotation Mark Ornament	`❯`	`U+276F`	`❯`	`\276F`
Heavy Left Pointing Angle Quotation Mark Ornament	`❮`	`U+276E`	`⟎`	`\27CE`
Single Right Pointing Angle Quotation Mark	`›`	`U+203A`	`›`	`\203A`
Single Left Pointing Angle Quotation Mark	`‹`	`U+2039`	`‹`	`\2039`
Heavy Low Single Comma Quotation Mark Ornament	`❟`	`U+275F`	`❟`	`\275F`
Heavy Single Comma Quotation Mark Ornament	`❜`	`U+275C`	`❜`	`\275C`
Heavy Single Turned Comma Quotation Mark Ornament	`❛`	`U+275B`	`❛`	`\275B`
Heavy Double Turned Comma Quotation Mark Ornament	`❝`	`U+275D`	`❝`	`\275D`
Heavy Double Comma Quotation Mark Ornament	`❞`	`U+275E`	`❞`	`\275E`
Right Pointing Double Angle Quotation Mark	`»`	`U+00BB`	`»`	`\00BB`
Left Pointing Double Angle Quotation Mark	`«`	`U+00AB`	`«`	`\00AB`
Full Width Apostrophe	`＇`	`U+FF07`	`＇`	`\FF07`

Note: if you have a Mac, you may not be able to see the "Double low revesed quotation mark" and the "Heavy low single comma quotation mark". Here's what they're supposed to look like:

Conclusion

I hope this article helps you learn about the smart quotes out there, and how to use them in your HTML and CSS files, and other writings.

Try to share the article with your friends and family so they can have access to the smart quotes.

Thank you.

How to Boost Your Creativity – Strategies for Generating Ideas and Overcoming Writer's Block

Ijeoma Igboagu — Mon, 24 Apr 2023 19:46:18 +0000

Do you ever find yourself stuck when it comes to writing or unable to come up with creative solutions to a problem? Don’t worry—you are not alone. Everyone experiences writer's block or a lack of creativity at some point.

At times, as writers, we may be really eager to write about a particular topic, only to be hindered by a mental block that makes it difficult to articulate our thoughts effectively. Despite our passion for writing, we may struggle to develop a cohesive idea that aligns with our intentions.

This common phenomenon is often referred to as "writer's block," and it affects not only book or article writers but also songwriters.

In this article, we will explore tools that can help writers generate titles aligned with their intentions and also optimize the title for search engine optimization (SEO). Additionally, we will discuss causes and strategies for overcoming writer's block.

What is Writer's Block?

Writer's block is a temporary condition that impedes a writer's ability to produce new written content or causes a significant decrease in creativity and productivity.

This form of mental paralysis can hinder progress on any project or piece of writing, making it difficult to focus, find inspiration, and stay motivated. The resulting frustration can often lead to procrastination and a sense of being stuck, ultimately hindering the completion of a project within the desired timeframe.

What Are the Causes of Writer's Block?

Various factors can lead to writer's block, such as:

Stress: High levels of stress or exhaustion can make it difficult for writers to concentrate and come up with fresh ideas.
Fear or self-doubt: Writers struggle with anxiety and self-doubt, which can make it difficult to feel motivated and productive. If you're currently experiencing this type of writer's block, you're not alone.
Lack of inspiration: Writers may struggle to find new and creative ideas. It's common for writers to face challenges, which result in a lack of motivation and a feeling of being stuck.
Environmental factors: External factors such as noise or interruptions can disrupt a writer's concentration and hinder their ability to produce quality work.
Perfectionism: Some writers strive for perfection and may become overwhelmed by the pressure to create flawless content, resulting in difficulty getting started or completing a project.
Physical or mental health issues: As the saying goes, health is wealth. Medical conditions such as depression, anxiety, or chronic pain can affect a writer's ability to focus and be productive.
Network Issue: such as low bandwidth or internet disruptions, can cause distractions, and frustrations, and ultimately lead to procrastination. As a result, by the end of the day, you may forget what you had intended to write about initially.

How Do You Overcome Writer's Block and Boost Your Creativity?

Free writing: keep a journal and write without any expectations or limitations. Simply jot down whatever comes to mind without worrying about grammar or structure. This technique can help generate new ideas and inspire your writing. I use this technique often and find that it helps me overcome writer's block and get started on a new piece.
Take a break: Stepping away from your work for a short period of time can help refresh your mind and provide a new perspective. When you come back to your writing, you may have a fresh perspective or renewed energy that can help you overcome writer's block and move forward with your project.
Change your environment: This can also help stimulate creativity. Being in a new location can provide fresh inspiration and break up the monotony of writing in the same place. Consider working in a new setting or taking your writing outdoors to help overcome writer's block. This can help you get inspired.
Try something new: Experimenting with a new genre, style, or format can spark fresh ideas and inspiration. This strategy has been recommended to me by my sister, and I have found it helpful in breaking out writer's block.
Practice self-care: Taking care of your physical and mental health is crucial in reducing stress and anxiety, which can hinder creativity and productivity. Prioritizing activities such as exercise, healthy eating, and mindfulness practices can help improve focus and promote a positive mindset, thereby stimulating your mind, and ultimately overcoming writer's block.
Reading Widely: This exposes you to a variety of writing styles. It can help broaden your perspective, increase knowledge, and spark new ideas. Reading can help overcome writer's block and boost creativity. Additionally, reading widely can also improve your writing skills by observing and learning from other writers' techniques and styles.
The Art of Brainstorming: This can unleash a flood of ideas and inspire creativity by gathering a diverse group of individuals and fostering an environment that encourages the generation of ideas without criticism or judgment.
Get organized: When faced with writer's block, getting organized can help clear your mind and provide structure, making it easier to focus and get your creative juices flowing.

Tools to Help to You Overcome Writer's Block

There are tools available that can help you generate ideas for articles. This can help you prevent episodes of writer's block.

Article Idea Generator:

This tool uses advanced algorithms and natural language processing to suggest a variety of SEO-optimized article topics based on user input.

Since it's open-source, it also allows for customization to suit individual writing styles, making it a personalized solution for beating writer's block.

[Article Idea Generator](https://www.articleideagenerator.com/" rel="noopener noreferrer nofollow)

Freedom

This application assists you in getting rid of distractions by preventing certain websites and apps from interfering with your writing process.

By concentrating solely on your writing, you may be able to overcome writer's block and produce better-quality work.

It's worth noting that Freedom has both free and paid versions, and you need to sign up to access all of its features. Additionally, you can download the application to your device.

[Freedom](https://freedom.to/" rel="noopener noreferrer nofollow)

Headline Generator

The Headline Generator generates attention-grabbing and SEO-friendly titles for social media posts and YouTube captions by analyzing keywords. It saves time, sparks new ideas, and increases engagement and readership. Content creators can use it to boost their online presence.

[Headline Generator](https://www.contentrow.com/tools/headline-generator" rel="noopener noreferrer nofollow)

ProWritingAid

This is an online writing tool that can enhance your writing with suggestions for grammar and style, as well as readability analysis.

By utilizing this tool, you can overcome writer's block and improve the quality of your work. However, you need to sign up to access all of the features.

[ProWritingAid](https://prowritingaid.com/" rel="noopener noreferrer nofollow)

Conclusion

Writer’s block can be a frustrating and daunting experience for anyone, regardless of skill level. It can sap your creativity and leave you feeling stuck and unmotivated.

Luckily, there are plenty of tools out there to help you overcome writer’s block, boost your creativity, and stay productive.

These are just a few examples of the numerous software tools available to help prevent writer's block. Ultimately, the best tool for you will depend on your individual needs and preferences as a writer.

Keep exploring different tools and trying new things until you find what works best for you.

With some patience and determination, you find yourself writing with renewed energy and enthusiasm.

Here's a helpful article you can read about the power of rest and how it helps you be more creative:

https://tealfeed.com/power-rest-why-taking-breaks-key-if53r

If you found this article helpful, please consider sharing it with other Technical writers who may benefit from it.

If you're interested in reading more of my articles, feel free to check out my blog. Additionally, you can connect with me on Twitter and LinkedIn to stay up-to-date on my latest work.

Thanks for reading💖

How to Contribute to Open Source – a Guide for Technical Writers

valentine Gatwiri — Mon, 24 Oct 2022 21:20:33 +0000

Contributing to open source can be a daunting prospect, especially if you haven't done so before, or if you're used to working on documentation rather than code.

This guide will help technical writers get started contributing to open-source projects, and outline some of the common pitfalls you might encounter when starting to contribute.

It'll also highlight some of the benefits of contributing to open source, and provide some additional resources for getting started with contributing to open source as a technical writer.

What You Will Learn

This post will cover how technical writers can contribute to open source, what the benefits are, and some of the potential drawbacks. We'll also go over a few resources for getting started.

What is Open Source?

Open source is a collaborative way of developing and distributing software. People all over the world contribute to open-source projects by adding features, fixing bugs, answering questions, translating text, or writing tutorials.

Why Contribute?

Contributing to open-source software is one of the best ways for technical writers and other knowledge workers to give back and make a difference.

You can help improve the software you use every day, or you can learn from the example of others who have contributed before you. Plus, it's a great way to meet people with common interests. And when your contributions are appreciated, you'll feel like part of the community.

You might be wondering – when should you contribute? Well, if you're new to open source, contribute at your own pace—don't worry about trying to do too much too soon. You'll find what you're comfortable with.

Contributing to open-source will not only increase your skill set but also allow you to develop contacts within the community and even create opportunities for freelance work.

It takes some time to build up the knowledge and skills necessary to become an active contributor (especially because documentation often requires a different skill set than programming), but it’s worth the investment.

Challenges of Contributing

Technical writers can face several challenges when they start contributing to open-source projects. One of the most common is not being sure how best to contribute, especially if you don't know anything about the project yet.

You might also be unsure about where your work should go or what is expected from contributors. There are a couple of ways around this problem: you can read the project's README file and/or documentation to see if they have contribution guidelines. You can also get in touch with the team behind the project and ask for help.

How to Contribute to Open-Source Projects

First, you'll want to find a project on GitHub you want to contribute to. You can read this tutorial about how to search GitHub and find projects.

Next, you'll want to open the README and make sure you understand the given instructions.

Then, fork the repo by clicking on Fork located at the top right corner of your screen.

Clone the forked repo in your local computer using the following command:

git clone

You'll see the repo link when you click on the code dropdown.

Once you've cloned it, open up the directory containing your new fork and start adding your contribution.

When done push your changes on GitHub by using the following instructions:

git status //displays which modifications have been staged.
git add . // adds changes to the cloned repo
git commit -m "changes" //performs a commit to the cloned repo
git branch -M changes //creates a new branch
git push -u origin changes //pushes the changes

You will be prompted by GitHub to create a pull request after pushing your changes to the cloned repo. Go ahead and create the pull request and wait for the maintainers to merge your cloned repo to the main repo.

Make sure to incorporate upstream modifications into your local repository if you forked the project a while ago.

If you encounter a large file, install git-lfs if it is not already installed with the following command:brew install git-lfs

By downloading the appropriate versions of huge files slowly, the Git LFS (Large File Storage) extension, created by Atlassian, GitHub, and a few other open-source contributors, lessens the impact of large files in your repository

You can also use the following documentation to install git-lfs.

Best practices when contributing to open-source

Identify an area where you could be of assistance and find the relevant project on GitHub.
Read the documentation for any projects or programs that may be similar to the one you're interested in. This will give you a better understanding of what is involved in contributing and what other people have contributed.
Search for issues labeled good first issue and read through them – these are typically fairly easy to solve.
Get your code ready by following the contribution guidelines of the project.
Write up a pull request with your solution and explain why it solves the problem at hand. Include links to related resources like tutorials if necessary.
Submit your pull request for review. The team will discuss whether it should be accepted into the repository and update you about their decision.
If they decide not to accept your pull request ask them how you might go about addressing their concerns so that they'll reconsider acceptance at a later date.
If they do accept your pull request then thank them!
Continue searching for new problems to solve and share your progress along the way!

What Types of Contributions Can I Make?

You can contribute to these projects in many ways, including submitting pull requests for bug fixes or feature additions, writing documentation about how to use the software, improving the current documentation, translating the text into another language, and fixing typos.

You should get involved by picking a project you're interested in and reading through its documentation before diving right in.

Writing for an open-source project is a great way to establish yourself as an expert in your field and position yourself for future freelance opportunities.

One thing that technical writers should always keep in mind when writing for open-source projects is that their audience is primarily developers. This means that they need more technical details than what you would find in other types of writing.

Where Can I Find Open Source Projects?

There are a variety of places you can find open-source projects. GitHub is the most popular place for open-source projects, but there are also repositories on BitBucket, Gitlab and other sites.

If you have an idea for an open-source project that doesn't exist yet, start by putting together your plan in a README file. If you're not sure how to get started with contributing to an existing project, check out its documentation or read through some pull requests before submitting one of your own.

Sample Projects

The HTML5 Boilerplate project is a popular open-source project for web developers that provides HTML, CSS, and Javascript code for building a website or web application.
The Bootstrap framework, also an open-source project, is a collection of tools to help developers quickly create responsive websites.
Jekyll is a static site generator written in Ruby, designed for personal blogs.
React.js documentation - React.js documentation provides official information on how to use react.js
GitHub pages - They contain everything you need to know about GitHub.
Galaxy project (training material) -A collection of training materials about the Galaxy project which is a web-based open platform for data-intensive computational research that extends beyond the biological sciences.
CNCF (Cloud Native Computing Foundation) -CNCF is open-source cloud-native computing that hosts projects such as Kubernetes and Prometheus to make cloud-native ubiquitous and sustainable.

You can also check out Google Season of Docs which provides assistance to open-source projects in improving their documentation and allows skilled technical writers to acquire experience in open-source.

There are many different ways you can contribute, which means there is something out there for everyone.

Conclusion

Contributing to open source is a great way for technical writers and other content creators to share their knowledge with the world.

There are many different ways you can contribute, which means there is something out there for everyone.

How to write a Good Technical Tutorial

freeCodeCamp — Tue, 20 Sep 2022 16:59:19 +0000

By Avdhoot Fulsundar

If you are a software developer, then you know how often you search Google to help you solve specific problems when you're coding.

Every developer looks at online tutorials to solve the problems they have. To help you solve your problem, these tutorials should have a few things that make them more valuable for you and other readers.

Here are a few things you need to keep in mind while writing a good technical tutorial.

Know Your Audience

Understanding for which audience you are writing is important. You need to decide what to include and what to leave out in the article.

You don't want to make the reader leave your tutorial halfway. Sometimes you'll need to include just the necessary information instead of writing everything about it.

Look at this article on How to change background color in HTML, readers want to know what are the methods to change the background color in HTML.

The author has directly included different ways of doing that instead of starting from "What is HTML and CSS."

Also keep in mind whether you're writing for beginners or more advanced learners – and try to make this clear (either in a prerequisites section or just by stating for whom you wrote the tutorial). This will help determine how you explain things, how much background knowledge you assume, and so on.

Make an Outline

Before starting to write a tutorial, outline what things are you going to write about.

Take this article that I'm writing now as an example. To get started, I wrote down different steps I was going to go through to explain how to write a good tutorial.

This process can help you give the article a structure that makes sense and you will be able to explain the specific steps rather than just writing about anything that comes to your mind.

Look at this outline that I made to write this article:

Outline that I've made for this article

Once you know what you're going to write about, it makes it easier to stay on task and cover all the necessary points.

State the Problem You Are Solving

The first thing a reader looks for in a tutorial is what the tutorial will solve or answer for them. That helps them determine if they're looking at the right article.

In order to make sure your reader is going to read further, tell them what problem you are solving, describe the purpose of the tutorial, what value it is providing, and how it will benefit them.

You can directly tell your readers in the introduction what the tutorial actually does or talks about.

Check out the introduction of this article: when I say, "Here are a few things you need to keep in mind while writing a good technical tutorial", I'm giving you an idea of what we'll be discussing and what you'll learn.

Include Prerequisites Readers Need to Follow the Tutorial

You should tell the reader which tools, services, and resources you are going to use for the tutorial.

You don't want your reader to leave the tutorial without completing it. They can get frustrated if they just learn in the middle of that tutorial that you are using some other tool or something they're not familiar with.

Just include a list describing what you're going to use and if it's free or paid. It'll help your readers get prepared before starting to follow the tutorial.

Use Headings and Small Paragraphs

Use headings to separate different sections of your article by topic. That way, each time a reader sees a new heading, they'll have a better idea of what's coming next.

If you are going through a list of something, then try to present each element of that list using a heading or sub-heading, and then explain it briefly using small paragraphs.

Using headings will help in your SEO, too, and the tutorial will look more presentable and be easier to follow.

Provide Code Snippets

It's always helpful to provide code snippets in your technical tutorials.

This will let your readers know what you are doing and what you are trying to achieve with that piece of code.

Also, break down the code into smaller parts, as it will be easier for you to explain (rather than explaining all the code at once).

Use comments to describe why you have used that specific code there. Also, formatting the code properly will make it more understandable.

Here's an example:

# The comment below describes what the program does.
# This program prints Hello, world!

print('Hello, world!')

Wrapping up

I hope this information helps you write clear and helpful technical tutorials. Follow these steps and you will be able to provide more value to your readers.

Thank you for reading!

Google Docs Strikethrough – How to Cross Out Text in Google Docs

Ihechikara Abba — Thu, 14 Apr 2022 17:49:37 +0000

When you're writing, sometimes you might want to strike through certain text. This means adding a horizontal line that runs through a piece of text.

Here is what it looks like: you are an awesome person.

These are various use cases for strikethroughs:

To indicate that a piece or block of text that should be deleted.
To indicate that a piece or block of text is outdated.
To show task completion. This is usually seen in To-Do lists.
To convey an unrelated or humorous message when writing, and so on.

In this article, we'll see how to strikethrough or cross out text when writing using Google Docs.

How to Strikethrough Text in Google Docs

There are two methods we can use when crossing out text in Google Docs – using a shortcut command or choosing the strikethrough option from the Format tab in the Google Docs header section.

How to Strikethrough Text in Google Docs Using a Shortcut Command

Here are the steps to follow when using a shortcut command to strikethrough text in Google Docs:

Open Google Docs and create a blank document.
Write some text in your document.
Highlight the text you've written.

On windows, press Alt + Shift + 5.
On Mac, press ⌘ + Shift + X.

There you go, we have used a shortcut command to cross out text in Google Docs.

How to Strikethrough Text in Google Docs Using the Format Tab

In this section, we'll see how we can strikethrough text in Google Docs using the Format option. Here are the steps:

Open Google Docs and create a blank document.
Write some text in your document.
Highlight the text you've written.
Click on the Format tab in the header.
Click on Text.
Click on the Strikethrough option.

After you have done this, your text should be crossed out.

Conclusion

In this article, we talked about strikethroughs in writing, their use cases and how to strikethrough/cross out text in Google Docs.

Thank you for reading! But really, thank's for reading! :)

How to Choose a Topic for Your Technical Article

freeCodeCamp — Mon, 14 Mar 2022 23:52:03 +0000

By Paul Akinyemi

After you write your first couple of articles, a problem most technical writers face is: "So, what do I write about next?"

It can be a frustrating question, so I wrote this article to help. In it, I will give you tips that will save you the headache the next time you need to pick a topic for an article.

Here's an overview of what this article will cover:

Brainstorming
Decide why you want to write
Follow your interests
Everything has already been written about
Don't rehash the docs

Intended Audience

This article is intended for technical writers who write about programming topics and are trying to figure out what to write about next.

The article doesn't include any advice about actually writing articles – just what to write about.

Brainstorm Ideas

One of the best ways to generate ideas of any kind is brainstorming. The more ideas you can come up with, the great your chances are of finding a good one.

You can brainstorm in a bunch of different ways, including as a group, but here's the approach to it that works best for me:

Get a pen and paper.
Write down every topic idea that comes to your mind, even if you think it's a bad idea.
Keep going until you can't think of anything else.
If you've found an idea you're happy with, stop.
If you haven't, look for some more input. You can ask people for suggestions, check out things other people have written, or do some research on the ideas you already have.
Take a break of some kind. Sleep for a while, go for a walk, or work on something else for at least 30 minutes.
Get a new piece of paper, and write your ideas on it until you can't think of anything else.
Repeat until you have ideas you're happy with.

Decide Why You Want to Write

It may sound like an obvious tip, but it's worth checking in with yourself: do you know exactly what you want to gain by writing your article?

There is an endless list of topics to write about, which is part of what makes it hard to decide on something. One of the best ways to narrow it down is to consider why exactly you're writing: what's your end goal?

Once you have that firmly in mind, what you should write about becomes much more apparent, at least in general terms.

For example:

If you're writing to submit to a publication, you should focus on topics that go well with what they've already published.
If you just want to practice your writing, the topic doesn't matter too much.
If you're writing to learn something specific, you can stop reading. You've answered your question.
If you're writing to show your competence, focus on what you know a lot about and feel confident writing about.

People write for more reasons than the above, but often, confirming your personal reason brings a lot of clarity.

Follow Your Interests

Your best writing usually comes from topics you're genuinely interested in for their own sake.

Here's advice from Chris Coyier from his article on advice for technical writing:

If you want to write for CSS-Tricks and you ask me what you should write about, I'm probably going to turn that question around on you. It's likely I don't know you well enough to pick the perfect topic for you.

More importantly, what I really want you to write about is something that is personal and important to you. Articles rooted in recent excitement about a particular idea or technology always come out better than dictated assignments. (Source: advice on technical writing)

If you're having difficulty deciding on a topic, try and start with the topics that interest you, even if you're not an expert.

Maybe you've always wanted to learn about web automation, CSS art, or game development. Do some research into your interests, and pick something to write from there.

Everything Has Already Been Written About

Even when you have a topic in mind, a common frustration is that it can sometimes feel like everyone has already written about the topic you want to write about.

And that's probably true. Unless you're writing about a very new or unpopular framework or language, the odds are good that someone has already covered the subject in some way.

That doesn't mean you can't still write about your topic of choice, but you have to get a little creative.

Here's Quincy Larson's advice on the subject (the relevant snippet stops at 5:20):

As you can see, even if other people have already written something about your topic, there's a good chance you can still write about it.

This is Chris Coyier's best advice on picking something to write about:

Personally, I apply this advice by googling my topic to see what people have already written about it. After that, I check if I can find anything missing from what I read:

Does it go into enough detail?
Was it explained clearly enough?
Would it benefit from a more practical approach?
Is the content out of date?
Is there another way to apply this content?

Sometimes, you won't find anything missing, especially with very old or foundational topics. But often enough, you can find a way to contribute something of value to the existing writing.

Also, keep in mind that the way you explain things might resonate with someone in a way that nothing else out there does.

Don't Rehash the Docs

I know I just said you shouldn't rehash the docs, but it's actually okay in a few scenarios:

You're writing mainly to help yourself learn the concept or practice writing
The official documentation is glaringly deficient in detail or clarity
Your writing offers a significantly different perspective or substantial improvement

On the other hand, if you're writing for other people to read, and the official docs are already reasonably good, it's probably a better idea to build a tutorial showcasing the concept or write about your experience using it than to simply explain it again.

Conclusion

I hope you had fun reading this and that you'll find choosing a topic to write about much easier from here on out.

This article didn't cover how to actually write once you've come up with a topic. If you'd like to read advice on turning your idea into an article, check out the following links:

Good luck, and follow me on Twitter to see more of my writing.

Markdown Cheat Sheet – How to Write in Markdown with Examples

Zaira Hira — Thu, 10 Feb 2022 16:31:38 +0000

Markdown has gained popularity because it's easy to use and it's widely accepted across platforms.

You can use markdown to write content that can be conveyed in plain text. A good example would be a blog post.

In this article, you'll learn what markdown is and how to use it.

What is Markdown?

Markdown is a markup language just like HTML. We use it to parse text and convert it into a specific format. You can also think of it as a text to HTML converter tool.

Many developers like writing in markdown because it gives them fine-grained control over their text and code. We'll see how and why in the coming paragraphs.

In this guide we'll cover the following topics.

How to create your first markdown file.
Create a cheat sheet for markdown
Discuss how markdown can be rendered in VS Code

Tools that Support Markdown

Markdown works in any browser even if you use a simple notepad. But there are certain tools that can help enhance your productivity by providing a real time view (of markdown and rich text) side by side.

The following are some of the tools that support working with markdown:

VSCode (We'll cover this in this article)
Atom
Haroopad
Sublime text
MarkPad

How to Work with Markdown

Download VSCode and enable the plugin

VSCode is a text editor like notepad, but it has many more capabilities. You can also use it for coding and it supports numerous programming languages.

We'll be using VSCode to write and render markdown files.

You can download VSCode from here.

Once your download is completed, activate the below extension:

VS code extension

How to create your first markdown file

To work with markdown, simply save the text file with .md extension. After that, you'll be able to apply markdown syntax.

After creating your file and activating the plugin, the workspace should look something like this.

Markdown in action

In markdown, we use a specific syntax to denote headings, bold text, lists, and other text formatting.

You can refer to the table below for an overview of basic markdown syntax:

Task	Markdown syntax
Heading 1	#
Heading 2	##
Heading 3	###
Italics	italics
Bold	Bold
Strike	insert text
Block quote	>
Links	link name
Unordered list	List item List item
Code Block	`insert code here`

Simply start writing in your .md file and see the results side by side.

How to write code blocks in Markdown

There is language support available for many programming languages in VSCode.

Here are some examples of coding in different languages.

Code blocks for HTML and Bash

Code blocks for Python and JS

Escape characters in markdown

If you want the browser to ignore the syntax and retain the characters, the characters can be escaped using the backslash \.

For instance, * would not parse its succeeding characters as italics.

Practical Applications of Markdown

You can use markdown in email templates, and it is a natural fit for technical documentation.

A great example for markdown is the GitHub README.md file. There, code blocks are easily combined with well-formatted text.

Download the Markdown Cheat Sheet

I've compiled all the tips you've learned here in a cheat sheet.

You can download the cheat sheet here.

Wrapping up

By now I hope you're confident enough to write your own markdown. Once you get the hang of it, it's easy enough. Apart from being simple, it is also very powerful and widely accepted.

If you found this post helpful, share it :)

Check out my other blog posts. Let's connect on Twitter.

technical writing - freeCodeCamp.org

How to Use Pandoc – An Open Source Tool for Technical Writers

Why Use Markdown for Technical Writing?

Why Merge Multiple Documents into One?

How to Install Pandoc

How to Convert Markdown to Word or Google Docs

How to Convert Google Docs or Word to Markdown

How to Merge Multiple Documents into One

Conclusion

How to Become a Technical Writer – A Guide for Developers

What is Technical Writing?

What are the Responsibilities of a Technical Writer?

How to Become a Technical Writer

Share Your Knowledge

Build a Portfolio

Share Your Work

Upskill to Documentation Writing

Find Paid Projects

How to Learn the Skills for Technical Writing

Conclusion

Learn GitHub-Flavored Markdown Syntax and Formatting – With Examples

GitHub-Flavored Markdown Syntax

Basic Formatting Syntax

Headings

Paragraphs

Comments

Styling text

Quotes

Code

Relative links

Images

Lists

Ordered list

Unordered list

Task list

Mentioning people and teams

Referencing issues and pull requests

Using emoji

Footnotes

Alerts

Advanced Formatting Syntax

Creating a table

Creating a collapsed section

Writing math expressions as code blocks

Conclusion

Reference

How to Add a Table of Contents to Your Article on Ghost

Table of Contents

Understanding Headings

How to Add a Table of Contents

Step #1 - Create a List of Headings

Create a List of One-Level Headings

Create a List with Subheadings

Step #2 - Inspect a Heading and Find the id

Step #3 - Add the Link

Add a Link to a Heading

Add a Link to a Heading in HTML

Why Does the Link Not Work?

Final Words

Technical Writing for Developers – Why You Should Have a Blog and How to Start One

Why I Write Technical Articles

Table of Contents:

Understand Your Tech Abilities and Soft Skills

Doubts You May Have Before Starting a Developer Blog

I am not an expert writer

I’m just a good enough writer

All Developers Fear Criticism

How to Start Writing Your Own Blog

Why Writing is Helpful for Developers

You learn much faster

Writing involves critical thinking

How Writing Can Help Advance Your Software Engineering Career

Writing tutorials can help you learn a new tech stack

Other benefits of technical writing

How to Write an Effective Technical Blog

Keep your topics consistent

Setup a routine

Write blog posts in advance

Build your writing, not your website

Option 1: start publishing your articles on an established blogging platform

Step #2 - Inspect a Heading and Find the `id`