DEV Community: James.Scott

How programming languages got their names

James.Scott — Sat, 04 Jan 2020 13:31:32 +0000

Phil Karlton once said there are only two hard things in computer science: "cache invalidation and naming things" and it's because of the latter that we have so many weird and wonderful names in technology. In this post I'm going to explore the names of a handful of common programming languages, revealing why they were chosen and where the words came from.

Perl

Perl was created by American developer Larry Wall in 1987. He initially chose the name Pearl because he felt it was short and memorable word with positive associations. However, as there was an existing language with the name, he changed the spelling to Perl. One existing backronym (an acronym created after the name) for Perl is Practical Extraction and Reporting Language. The word pearl came via the Old French perle meaning 'a bead' or 'something valuable' and the Latin perna meaning 'leg' which extends to the name of a mollusc apparently shaped like a leg of mutton.

Ruby

Ruby, the language the Dev.to site was developed with, was created by Japanese developer Yukihiro "Matz" Matsumoto in the 1990s. Influenced by Perl, he also wanted to use the name of a precious stone and choose Ruby because it was the birthstone of a colleague and the next birthstone in the monthly sequence after Perl: June's is pearl and July's is ruby. The word ruby comes from the Old French rubi meaning a 'reddish precious stone' from the Latin rubeus meaning 'red'.

Python

Dutch programmer Guido van Rossum designed Python in 1991, naming it after the British television comedy Monty Python's Flying Circus because he was reading the show's scripts at the time. He wanted a name that was "short, unique and slightly mysterious". The word python comes from the ancient Greek Puthón, the name of a huge serpent killed by the god Apollo. It has been used to refer to various large, heavy-bodied, non-venomous snakes that constrict their prey since the early 19th century.

Java

Java was designed by James Gosling while he was working at Sun Microsystems in the early 1990s. The project was initially called 'Oak' before a highly caffeinated brainstorming session produced the name 'Java' (although they very nearly went with 'Silk'). Java, or Jawa in Indonesian, is the name of a large island in Indonesia that produces strong, dark and sweet coffee. It’s name can be traced back to the Sanskrit word yavadvip, yava meaning ‘barley’ and dvipa meaning ‘island’. Java has been a slang term for coffee in the United States since the 1800s.

Kotlin

Kotlin, the language released by JetBrains in 2011, takes its name from Kotlin Island in Russia. The team wanted to use an island name like Java had - although it was technically named after the coffee rather than the island! Kotlin (Котлин in Russian) used to be part of Sweden and was known as Kettusaari by the Finns, meaning 'fox island', and Ketlingen by the Swedes, which possibly stems from the lower German kettel meaning 'cauldron'. After Peter the Great and his Russian forces won control of the island in 1703 it was renamed Kotling, later shortened to Kotlin.

Swift

There is no clear answer to why Apple chose the name Swift but it's definitely not named after Taylor Swift as someone asked on Quora! My guess is they wanted to give the impression of something fast. The word swift means 'moving with great speed or velocity' and can be traced back to the prehistoric swipt- meaning to 'move in a sweeping manner'. The swallow-like bird became known as a swift from the 17th century and is used as the programming language's logo.

Find this interesting?

If you found this interesting, I've posted an infographic of the origins of more programming languages here. See low-res version below:

You can follow me on Twitter at @TheStrangeRoots for Tweets about the origin of different words used in technology.

A case for code comments?

James.Scott — Wed, 13 Nov 2019 19:35:27 +0000

If there is one topic that divides the developer community, it's whether to use use code comments or not. Some believe code should be self-documenting and code comments are a code smell, a sign of an underlying problem. On the other side of the fence, others believe that self-documenting code is a fairytale and code comments are useful. So what's the answer?

The argument against code comments

Supporters of self-documenting code often highlight that "readable" code and that comments that can become stale or out-of-date and misleading as a result. Allen Holub argues that well-designed code that uses descriptive names shouldn't need code comments:

// Detect dark theme var iframe = document.getElementById('tweet-1134955155466539008-643'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1134955155466539008&theme=dark" }

Similarly in this post on code health developers Dori Reuveni and Kevin Bourrillion wrote: "While reading code, often there is nothing more helpful than a well-placed comment. However, comments are not always good. Sometimes the need for a comment can be a sign that the code should be refactored."

Is self-documenting code a myth?

Those opposed to self-documenting code believe it's something of a myth and perhaps more a reflection of programmers' hatred of writing documentation:

// Detect dark theme var iframe = document.getElementById('tweet-3559283285-379'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=3559283285&theme=dark" }

Along the same lines developer and co-founder of Write the Docs Eric Holscher called self-documenting "the biggest documentation myth in the software industry in this post, arguing that code comments and documentation still have value.

Meanwhile Jef Raskin wrote that while he endorsed the techniques that some programmers claim make code self-documenting, he also argued that these methods cannot provide the documentation necessary for reliable and maintainable code:

"The fundamental reason code cannot ever be self-documenting and automatic documentation generators can’t create what is needed is that they can’t explain why the program is being written, and the rationale for choosing this or that method. They cannot discuss the reasons certain alternative approaches were taken.

So when is it okay to use comments?

The most common scenarios for needing to use code comments is if your code is particularly complex, it's absolutely impossible to make your code self-explanatory or you want to explain why you did something a certain way. Another popular shared principle for using code comments is:

Code explains the how, code comments explain the why.

As a documentation advocate, I've personally always seen the value in comments, particular for a beginner or junior developer. Code is designed to be read and executed very literally by machines, whereas no two humans are the same. Our understanding is impacted by a whole host of factors including experience, knowledge level and grasp of a particular coding language. Rather tellingly, the PC Magazine definition of "self-documenting code" also comes with this footnote:

It's very subjective [...] what one programmer thinks is self- documenting may truly be indecipherable to another...

Tips on writing code comments

If you're going to use code comments, there are a number of thing you can do to make them as helpful and useful as possible:

1. Use descriptive names

Before you even consider using a code comment, check you can't use a more descriptive name. For example, instead of using a comment:

int time = ... // Returns time in seconds

You could use a more descriptive name:

int timeInSeconds

2. Don't comment the obvious

If it's obvious what the code does, don't duplicate this in a comment. For example, don't do this:

print "Hello, World!" // Console prints "Hello, World!"

3. Keep it concise

I would try to keep the number and length of comments to a minimum. There is nothing worse than finding a wall of text in someone’s code. Studies have actually found a correlation between sentence length and user comprehensions.

4. Avoid ambiguous words

Certain words can create ambiguity in your documentation. Some prime examples of ambiguous words include:

Should: Suggests an action is optional rather than mandatory. For example, "You should do x to make this work". In most cases its better to use the word must instead.
Please: Everyone writes please because it's polite but it makes an instruction sound like a request rather than a requirement. Be rude, don't say please.
This and it: Ambiguous pronouns like ‘this’ and ‘it’ make it unclear what the subject or object of your sentence is. Always clarify if you can.

5. Don't use jargon

Don’t use jargon or acronyms that not everyone will understand. Sometimes we get so caught up in our work, it’s easy to forget what is a common, everyday language for you, might be completely alien to someone else.

For example, instead of writing an acronym write it out in full the first time your write it. For example: Java virtual machine (JVM), Kubernetes (K8s), JSON Web Token (JWT) etc.

6. Avoid passive voice

Passive voice creates questions and ambiguity. Always include the subject that is performing the action if possible. For example:

❌ Passive voice: "The web service is queried." What is sending the query?
✅ Active voice: "The user queries the web service." It is clear what the subject of the sentence is.

7. Avoid slang and dialect words

Using slang or dialect in code comments is likely to cause confusion.
For example, a British developer might write:

\\ Sorry, I wrote this code when I was knackered so it might be rubbish.

In this case, dialect words like 'knackered' (tired) and 'rubbish' (garbage or trash) might not make sense to English speakers from other countries let alone non-native English speakers!

8. Stick to one language

Don’t write in multiple languages. Most people might understand common Latin words but not everyone will understand them so think about using friendlier alternatives:

e.g.: Use For example, instead.
i.e: Use that is instead.
N.B: Use Please note or Note:.

9. Avoid location & temporal words

Time never stops and the location of code may change at some point in the future. As a result, it's best to avoid the following:

🗺️ Location words: Above, below.
🕰️ Temporal words: New, latest, current, up-to-date.

10. Be cautious with humour

Everyone likes a joke every now and then. Wouldn’t life be boring if we lost our sense of humour? I found this example of humour on Stackoverflow:

stop(); // Hammertime!

While this is funny if you know the MC Hammer song, it’s worth bearing in mind some people won't find this funny if they don't understand the cultural reference. A comment like this may well end up confusing or annoying some people.

Summary

If you skipped to the end, in summary... although some people are advocates for self-documenting code, others think code comments can be useful if your code is complex or if you feel the need to explain why you did something a certain way. In my opinion:

Using code comments > Writing code people can’t understand

If you are going to use code comments, my tips include:

Use descriptive names.
Don't comment the obvious.
Keep it concise.
Avoid ambiguous words.
Don't use jargon. Define acronyms if you do.
Use the active voice where possible.
Avoid using slang.
Don't write in Latin.
Avoid location/temporal words.
Be careful with humour (probably best to avoid!).

How to write a kickass README

James.Scott — Mon, 28 Oct 2019 18:57:08 +0000

Arguably the single most important piece of documentation for any open source project is the README. A good README not only informs people what the project does and who it is for but also how they use and contribute to it.

If you write a README without sufficient explanation of what your project does or how people can use it then it pretty much defeats the purpose of being open source as other developers are less likely to engage with or contribute towards it.

TL;DR - Too long? Skip to the end and use my template.

What is a README?

Essentially a README is a single text file (.txt or .md) that acts as the one-stop shop documentation for a project or directory. It is usually the most visible piece of documentation and landing page for most open source projects. Even a README file's name in all-caps is designed to catch your reader's attention and ensure it is the first thing they read.

There's evidence that READMEs date back as far as the 1970s. The oldest example I could find was this README for DEC's PDP-10 computer which is dated 27th November 1974. Although the origin of the name README is disputed, the two most popular theories are:

Programmers of the original mainframe computers which came with punch cards, would leave a stack of paper instructions with “READ ME!” written across the front.
The name is a nod to Lewis Carroll's Alice in Wonderland in which the main character Alice finds a bottle of potion labelled “DRINK ME” and cake labelled "EAT ME" which make her change in size.

What should you include in a README?

Ok, so what should an awesome README file contain? As a starting point, I would recommend you include the following key things:

1. Name the thing
Don't forget to give your project or feature a name. There are a surprising number of projects on GitHub that don't have a name.

2. An introduction or summary
Write a short two or three line introduction explaining what your project does and who it is for. Also leave out headings like 'Introduction', 'Summary' or 'Overview' - it's obvious this is an introduction.

3. Prerequisites
Immediately after your introduction add a section titled listing any prerequisite knowledge or tools anyone who wants to use the project might need before they begin. For example, if it runs on the latest version of Python, tell them to install Python. Here's an example:



Prerequisites

Before you continue, ensure you have met the following requirements:

* You have installed the latest version of Ruby.
* You are using a Linux or Mac OS machine. Windows is not currently supported.
* You have a basic understanding of graph theory.

4. How to install the thing
Provide installation steps! It's amazing how many projects I've come across that only provide basic usage instructions and expect you to magically know how to install it. Make sure to break the installation down into numbered steps if it requires multiple steps.

5. How to use the thing
Add steps for how to use the project once the user has installed it. Make sure to include usage examples and a reference explaining command options or flags if you think they will be helpful. If you have more advanced documentation in a separate file or site, link to this from here.

6. How to contribute to the thing
Provide steps for contributing to the project. Alternatively you might want to create a contributor's guide in a separate file and link to this from your README if you want people to read it before contributing pull requests to your project.

7. Add contributors
Credit any contributors who have helped with the project in an author section. It's a nice way to make open source feel like a team effort and acknowledges everyone who has taken the time to contribute.

8. Add acknowledgements
Similarly, if you have used anyone else's work (code, designs, images etc) that has a copyright that requires acknowledgement, you might want to add that here. You can also acknowledge any other developers or institutions who helped with the project.

9. Contact information
You might not want to do this is you're an extremely private person but if someone has questions, wants to collaborate with you or is impressed enough with your project to offer you a job opportunity, it makes sense to have your contact details front and centre.

10. Add licence information
You definitely want to include licence information if applicable. Startups and other companies who rely on third-party software are unlikely to be able to use your project unless you provide this. Check out choosealicense.com or opensource.org for a list of licences you may be able to use.

Add flare to your README 🔥

If you really want to make your README stand out and look visually appealing you can do things like:

Add a logo: If your project has a logo, add this at the top of your README. Branding makes a project looks more professional and helps people remember it.
Add badges or shields: You can add badges and shields to reflect the current status of the project, the licence it uses and if any dependencies it uses are up-to-date. Plus they look pretty cool! You can find a list of badges or design your own at Shields.io.
Add screenshots: Sometimes a simple screenshot or set of screenshots can say far more than a thousand words. Be warned though, if you do use screenshots you will need to update them each time you update your project.
Use emojis?: A lot of projects seem to use emojis these days, although it’s up to you whether you want to use them. They can be a good way to inject a bit colour and humour into your README and makes the project feel a bit more human.

If you're using All Contributors to acknowledge contributions, you could use their emoji key to denote different contributions types:

* 🐛 for raising a bug
* 💻 for submitting code
* 📖 for docs contributions etc.

This is what GitHub badges or shields look like for reference (No doubt you've seen them before!):

My template

I've created a template that covers most of the recommendations made in this post. Feel free to fork the repository, make suggestions to improve it or customize it for your own purposes! You can find my template on GitHub here.

Resources

If you want more advice on READMEs, I'd also recommend these resources:

Daniel Beck's talk 'Write the Readable' from Write the Docs in 2016.
Lorna Jane Mitchell's talk 'Github as a landing page' from API the Docs 2019.
Check out Franck Abgrall's README generator.

My bitesize Unix tutorial (with pixel art)

James.Scott — Fri, 18 Oct 2019 12:33:51 +0000

While it might not be everyone’s cup of tea, Unix command line is incredibly useful to learn. Unix-based operating systems are under the hood of everything from Android phones to Chromebooks, Macbooks and even Playstations so there’s a pretty high chance you have used a *nix-powered device at some point in your life.

Learning Unix command line offers you a quick and powerful way to carry out tasks like file management, troubleshooting and customisation. Plus the next time you watch Mr Robot you might actually be able to understand some of what Elliot is typing!

Inspired by the covers of Julia Evans’ programming zines, I’ve created a tutorial to explain most of the commonly-used Unix commands, along with some accompanying pixel art — specially designed for people who don’t want to make a meal out of learning Unix 😉.

Entrée — Listing files and directories.

To start using Unix, it’s important to know how to navigate your way around your file system and its various directories:

ls (list segments — like a lemon!) — lists the files and directories in your current working directory. You can use different options with ls to sort or display additional information:

ls -l: displays files + permissions, owner, group, size, time and name.
ls -t: sorts files by time.
ls -r: sorts files in reverse order.

cd (change directory) — change your current working directory to another folder. You can specify the file path you want to move to as follows:

cd /usr/folder/subfolder

You can go back to the previous directory with cd -or move up one folder with cd .. or move up three folders with cd ../../...

pwd (print working directory) — displays the path of the current working directory you are in. Not really used for much else, just a good way to find out where on earth you are if you get lost!

mkdir (make directory) — creates a directory if it does not already exist. For example, to create a directory called “stuff”:

mkdir stuff

You can also make subdirectories using the -p option:

mkdir -p /home/stuff/morestuff

You can also use rmdir to remove a directory.

Starter — File operations

The next things to familiarise yourself with are copying, moving, creating and removing things:

cp (copy) — creates a duplicate of file or directory. To use it, type cp followed by the source file and the new file name. For example:

cp myfile1.txt myfile2.txt

Alternatively enter the source file name and location you want to create a copy in. For example:

cp myfile.txt /Users/your.name/Documents

mv(move) — move one or more files or directories from one location to another. Like cp it follows the format, mv sourcefile destination. For example:

mv ~/Desktop/myfile.text ~/MyFolder

touch — a quick way to create a file or multiples files. You can also use touch to change a file’s timestamp. Pass the name of the file you want to create as follows:

touch filename.text

If a file already exists with that name, touch updates the file’s access time (last time it was read), modification time (last time the contents were modified) and change time (last time the file’s metadata was changed).

rm (remove) — delete files. Enter the command and the file’s location:

rm /home/Desktop/-file.txt

Be warned rm can be quite a dangerous command to use if you don’t know what you’re doing. The one to really avoid is the dreaded rm -rf / which essentially deletes every file in your Unix system. Linux blogger Wayne Richardson posted a video of what happens if you run it if you’re curious:

Main — File searching, permissions and ownership.

You can search for files and directories and change the permissions and ownership for different files and directories:

find — find files and directories in your system. For example:

find ./directoryname -name file.txt

You can also find all files with a certain pattern. For example, all files that end .txt:

find ./directoryname -name *.txt

grep (global regular expression print) — search for text or search within a specified file for text matching a given string. You can couple it with the -i to make case insensitive searches:

$grep -i "grape" wine.txt

This would return:

Grape varieties includes cultivated grape, whether used for wine, or eating as a table grape, fresh or dried (raisin, currant, sultana). The origin of the word grape comes from a Frankish or other Germanic word 'grap' meaning "hook".

You can also use grep to count the number of times a word appears in a file:

$grep -c "grape" wine.txt

For this file the output would be 4.

chmod(change mode) — changes the permissions for files and directories. There are three classes you define permissions for: Owner (the owner of the file), Group (users of the same group) and Others (anyone else). You enter one of the following numbers for each class when you run chmod:

0 — No permission.
1 — Execute.
2 — Write.
3 — Write and execute.
4 — Read.
5 — Read and execute.
6 — Read and write.
7 — Read, write, and execute.

For example, chmod 777 grants read, write and execute permissions to all classes and chmod 755 grants all permissions to the owner of the file but only read and execute permissions to other users.

chown(change owner) — changes ownership of files and directories in your file system. To change the owner of a text file:

sudo chown myuser myfile.txt

Extras — Comparing, linking, tailing and killing.

You can compare files, link files, output the tail of files and kill processes:

cmp — Compare the bytes between different files. If there are no differences between the two files, no output is returned. The format for using cmp is:

cmp -b textfile1.txt textfile2.txt

The output for files with several differences is:

textfile1.txt textfile2.txt differ: byte 20, line 1 is  56 . 162 r

cat(concatenate) — use it to create a file, link multiple files together or display the contents of a file. For example, to link or “concatenate” two text files (file1.txt and file2.txt) to create new text file:

cat file1.txt file2.txt > file3.txt

tail — output the “tail”, the final part, of a file. By default tail outputs the last 10 lines of a file. You can use tail as follows:

tail textfile.txt

To output a greater number of lines, you can use the -n option:

tail -n 50 textfile.txt

kill — terminates a process. To see the signals you can kill run: kill -l. You can terminate a specific process as follows:

kill -s signalName PID

Desserts — More, Curl, SSH and Sudo.

Some additional commands you can use in Unix include more, cURL, SSH and Sudo:

more — display more text on the screen. To use more to display the contents of a file beginning at line 10:

more +10 myfile.txt

curl (Client URL) — a command line tool for transferring data over various protocols (HTTP, SMTP, LDAP, SCP etc). This comes in-built with MacOS and most Linux-based operating systems.

You can use cURL to send data or retrieve data over HTTP using an API request. For example, if you set up a webhook with Slack, you can use cURL to send a message to a Slack channel:

curl -X POST -H 'Content-type: application/json' --data '{"text":"Good morning everyone!"}' your_webhook_url

ssh (Secure Shell) — use it to operate securely over an unsecured network. The syntax for using ssh to login to a remote host is as follows:

ssh remote_host

Alternatively to ssh into the remote host as a root user. For example, this might be useful if you wanted to edit configuration files on a system in a virtual machine:

ssh root@remote_host

sudo (superuser do) — allows you to execute commands as a superuser. You can use sudo if you know the root password for your Unix system. For example to shutdown your machine using sudo:

sudo shutdown -r now

Drinks — Text editors.

There a number of core text editors you can use in Unix-based operating systems:

vi — the original text editor created for Unix by developer Bill Joy. Despite being released way back in 1976 it is still one of the most popular text editors for Linux-based systems.

vim (short for Vi Improved) — is a clone of the original Vi editor. Enhancements with Vim are the inclusion of plugins, the comparison and merging of files, and the ability to edit compressed files in formats such as gzip, zip and tar.

emacs (Editor MACroS) — another old-timer of a text editor. Like Vi, it was also released in 1976 and is one of the oldest open source projects still in development.

One cool tip if you launch Emacs is if you press Esc, type 'x' and type 'pong', it launches a game of pong:

This also works for tetris, snake, and solitaire (the marble game not the card game!).

nano — another editor for Unix-like operating systems. Initially released in June 2000, GNU nano is a simple text editor that’s very beginner friendly.

You can also use open-source text editors like Atom or Sublime if you prefer. These come with way more bells and whistles (things like linters to check there are no syntax or stylistic errors in your code). Hopefully some of this tutorial was useful. Good luck on your *nix adventures and remember to be careful with rm!

Note: Here is the full “menu” of pixel art if you want to download it.

How to build a documentation culture

James.Scott — Mon, 07 Oct 2019 11:32:09 +0000

Some of you probably don’t like writing documentation, most of you might even hate it. Writing docs often seems to be treated like the annoying but necessary task that is left until the last minute or sometimes forgotten about altogether. However, writing documentation is important for a number of reasons:

Not writing good documentation creates technical debt.
If you have poor docs, your colleagues (new team members in particular) or your end users have to ask you questions — this costs you time!
Without docs, you create knowledge silos where only a few engineers know how an aspect of your technology works. If these people leave your team it creates knowledge gaps.

If you think documentation is lacking at your company, whether it is a tech startup or a mature software company, there are a number of things you can do to try and build a better documentation culture.

1. Find someone to drive it

If you don’t already have a technical writer, UX writer or content specialist in your team and you have the budget, then hire one! They will become the foundation of establishing your docs culture.

Alternatively, you could try finding a “documentarian” — or “friend of the docs” — a programmer or perhaps a tester who is a good wordsmith and knows enough about your existing documentation and is willing to help drive the documentation effort.

2. Create a style guide

You can establish a form of quality control by picking or writing a style guide. This becomes your reference to ensure best practices and for things like terminology, capitalisation, syntax and tone and voice. If you don’t have the time or resources to write your own, you can adopt an existing one. Most technical writers refer to one of the following:

Microsoft Writing Style Guide (formerly Microsoft Manual of Style)
Chicago Manual of Style
Google Developer Documentation Style Guide.

You will also find some useful style resources at Write the Docs, a global community of people who care about documentation. There is even an entire page about style guides!

3. Use spell checkers and linters

Another way to establish consistency in your technical content is to encourage the use of spell checkers and linters. If you use open-source text editors like Atom or Sublime, you can install free spelling checking linters to help drive the accuracy and consistency of spelling and grammar. Some linters and tools you could consider include:

Alex: Linter available on multiple platforms.
American linter: Linter to make spelling American again. This is useful if you're from Europe, Asia or Africa but work for a US-based company who use American spelling.
Hemingway: App that checks content for passive voice and gives a readability grade level (a high grade level means your text may be confusing or tedious for the reader).
Write Good: Linter for English prose for developers. Available for Atom and Visual Studio.
Vale: A natural language linter that supports plain text, markup and source code comments. Available via CLI and as a desktop app.

Alternatively, you can create some form of presubmit check or filter to prevent specific typos or spelling mistakes. It may be little heavy-handed but I have created several presubmit checks to prevent developers in my current team from using ambiguous terminology.

4. Raise bugs

Another good way to raise awareness about documentation is to raise bugs against spelling or grammatical issues in your product itself or in the codebase.

When I joined a startup, I was initially nervous about raising bugs and interrupting developer velocity but after a few months of highlighting things like spelling issues, passive voice and typos, more and more engineers started coming to me for advice about content such as error messages, release notes, parameter names and code comments so we were able to ensure the text was correct in the first place.

5. Reward writing

While it might sound cynical, offering your colleagues rewards or incentives for contributing to the documentation can work. Some things you might consider include:

Running a "doc-a-thon" or one-day docs sprint and offering prizes to the people who contribute the most documentation changes.
If your company runs a peer bonus scheme like Bonusly, give contributors peer bonus points for their documentation efforts.
Offer physical rewards or swag for contributions to docs such as stickers or mugs.

As a naive junior technical writer, I even had some success with buying chocolate bars for developers who helped me with documentation but I’m not sure this is the healthiest option for your colleagues or your wallet!

6. Offer documentation training

If you’re a solo documentation writer in a large team of developers, you can’t realistically be expected to write everything. Your best bet is to teach your team some documentation best practices to improve the quality of your docs. Some topics you might want to cover include:

Voice: Using active voice instead of passive voice. The latter can create ambiguity.
Ambiguity: Avoiding the use of words that can create ambiguity. For example, if an action is mandatory use ‘you must do x’ instead of ‘you should do x’. The word 'should' suggests an action is optional.
Audience: Encourage your team to think about who they are writing for and any prerequisite knowledge or tools they might need.

7. Give talks about documentation

I used to be terrified of public speaking but over the past two years, I’ve given a number of internal and external talks about documentation and best practices.

It’s not only been a great way to test yourself and overcome your fears (if you’re not a comfortable public speaker) but it also helped to raise awareness about the importance of technical documentation both at your company and in the wider community.

8. Use the open source community

If your product is open source, you can reach out to technical writers and documentarians in the open source community to help with your documentation.

Some companies like Google run open source initiatives where they actually pay technical writers to contribute to open source projects. See Season of Docs for more details.

Summary

So in summary, if you want to get started and build some form of documentation culture and improve your company’s technical content:

Find a writer or “documentarian” to drive the docs.
Create or choose a style guide to establish consistency.
Use spell checkers or linters to establish quality.
Raise bugs to raise documentation awareness.
Reward writing to encourage others to contribute.
Offer training to empower your colleagues.
Give talks to inspire and teach others about docs.
Use open source if you need more help!

There are probably lots of other things you can try but if you attempt some of these suggestions, I think you’ll be on your way to creating a documentation culture at your company. Good luck!