Never stray from the way.

Writing

I often receive resumes from people looking for a job and asking me for help. To all of them I always ask: "Do you have a website ?", "Do you write ?". And most of the time, the answer is negative.

Writing skills are important because they allow the reader to get their first impression of who is the writer. For example: writing skills displayed in resume, cover letter email communications, website. In my humble opinion, if you're looking for a job as a software engineer, you should have a tiny space on the internet. A space in which you write about what you experiment, what you code, what you build.

This article is an attempt to answer, why I think everybody (every software engineer) should have a website. Or at least, why everybody should write. This article is also kind of a recap of a talk I gave for the Dakar Institute of Tecnology.



Some reasons for you to start writing:

1. Improve your knowledge on a topic

You'll often have to write about subjects that you are not familiar with, so finding quality sources quickly is a skill you'll develop. Before you write a single word, you need to do your research about the topic you're writing on. The more you do research, the more you find quality sources, the more you improve your knowledge.

2. Organize your thoughts

You can write down more than you can easily remember, so that your capacity to consider a number of ideas at the same time is broadened. Once those ideas are written down, you can move them around, change them. You can also reject those that are finally not good enough. You will stay with good, original clearly defined ideas. And you will be able to organize and communicate them easily.

3. Share your expertise, meet fellow specialist and grow your knowledge

Knowledge is the only thing that grows when shared. Sharing your knowledge helps you grow your knowledge by doing research, synthesizing multiple and different viewpoints. Sharing your expertise means inviting people to read you, inviting people to a new conversation. A conversation is always an occasion to meet new people and to grow as a human.

4. Make money

Even professions that don't focus on writing require written communication skills. The tech industry for example, is more and more looking for people who are able to write. Those writings include things like instruction manuals, user manuals, journal articles, product descriptions, memos, wikis, documentations, etc...

You can have a look :

By the way:

disclaimer: I'm not paid by anybody to share those job offers


What are the topic to write about:

Coming up with writing inspiration is tough. My advice would be, in all the cases, always write about something you really like, or something you really enjoy. As a technical writer, you can write different kinds of articles:

1. Story

Human beings are interested in stories about people. If your reader knows you a little through your blog, the reader will remember who you are and the reader will be more interested by your technical articles. Here you'll find different kinds of stories.

2. Opinion

Giving an opinion is a common way of interacting with other people. Of course you don't simply share an opinion, you'll also share the compelling and interesting argument that support this opinion. Also, please don't spend your time attacking others people or spreading controversial ideas. Here is an axample of a shared opinion.

3. HOW-TOs

An how-to is a document providing detailed and practical step-by-step guide on how to do something. In a precise, step-by-step approach, you should walk your reader through the process. You should make sure your reader can reproduce the same results by following the provided steps. Example of an HOWTO.

4. How something work

There are people like me who want to know how almost everything works. This kind of article is suitable when you want to deep dive into a very specific topic. For example, somebody already using Django sessions, may be suddenly wondering how does Django sessions work under the hood ? Here is an article showing how Django sessions work.

5. Reviews

You have read, used, tested, played with something. In a review, your attempt will be to write about what was your experience. You'll describe the thing, you'll share what were your feelings about the thing, you'll show the strengths and the weaknesses of the thing. Example of review.


Identifying the target audience:

Identifying your intended audience will help you write effective content that achieves your goals. What are you writing ? Who are you writing for ? Knowing your audience will help you adapt your content accordingly. And if you don't know who to write for, then the following is a serie of questions you can ask yourself:

  • Who am I writing for ?
  • What subject am I writing about ?
  • What does my audience already know about the subject?
  • What does my audience want to know about the subject?
  • What are the questions will my audience have?

Finding the audience:

For example, as a Python specialist, the audience can be found in different places. Pycoder weekly news want to hear from you about projects you are working on, conferences you are running, and articles you want to share.

Awesome Python is another newsletter who want you to contribute links to blog posts, tutorials, libraries, events, videos, books.

You can als share your posts on Lobsters, on Tilde News, on dev.to, on towardsdatascience.


Improving your writing:

The following is what I recommend. In all the cases, you should find what is best for you.

1. Practice

The most effective writers write every day, at least a bit. The more you write, the more your brain form connections between neurons. Those connections get stronger the more often you write. After some time and regular practice, you no longer have to think about it. This is when writing becomes a habit.

2. Make time

Prepare to spend between 90 minutes and 3 hours writing. But hey, 15 minutes can be useful if you do it every day. Don't fool yourself, thinking you'll wait for a big chunk of free time to start. That will never happen.

3. When

You are much smarter and more resilient after you have slept properly and ate. Again, find what suits you best. According to some studies, creativity peaks in the morning. My experience tells me that's true.

4. Frequency

Write only when you feel it.


Tools for writing... SSG:

You should provide yourself with the right technology. Here again, I can tell you what I do, but there are plenty of differents tools, you should always find what suits you best.

I've choosen to build my website using a Static Site Generator (SSG). An ssg is a tool that generates a full static HTML website based on raw data (text files) and a set of templates (html, css, js files). :

Image source


Why SSG:

  • No need for internet for writing, no need to login somewhere before writing.
  • no need for a particular environment, just a text editor, and a browser.
  • No vendor lock in, no dependency on any product for writing or migrating your content.
  • No need for a program to dynamically generate webpages. Web pages load faster.
  • No dependencies running on the server, just a web server. Increased security

I'm convinced, can you show me an example please:

The article you're reading right now, was generated from a markdown file using an SSG named Zola and a theme named Oceanic Zen.



To finish this article, I would like to quote Leslie Lamport


"If you’re thinking without writing, you only think you’re thinking."

— Leslie Lamport


Links:

To learn more on this topic, I strongly recommend the following links:

Links again:

Even more links:

Things that were discussed during the talk: