High-level Guidelines

Kite Answers provides high-quality answers to the most commonly asked Python programming questions. With each article we publish, we aim to take a commonly asked programming question (as seen on Stack Overflow) and write a much better answer.

Governing Philosophy

Kite Answers fills a different niche than existing programming resources. There are many excellent tutorials and blog-length posts showing how to use different Python features. These are great, and we don't want to replace them. Instead, we want to offer a more targeted resource, to answer simple questions in a short, copy/pasteable format.

Imagine that you are a programmer in the middle of a task, and you run into a roadblock. Perhaps you need to iterate through two lists simultaneously and forgot the zip function, or perhaps you want to do a complex sorting operation of a Pandas dataframe and don't know the syntax. In either case, you may find yourself sorting through several tutorials or StackOverflow posts, reading several solution and having to compare them yourself. This is time consuming and takes you out of the flow of programming. This is the problem we want to solve.

To achieve this, we answer specific questions simply and concisely. We assume competence of the programmer proportional to the question at hand. We do not attempt to teach the basics. For example, a question about map demonstrates the syntax and an example without attempting to explain functional programming. However, we do attempt clarify when possible and provide links to further resources. In the map example, we provide a Further Reading link to a more thorough tutorial on functional programming paradigms. In order to clarify we also implicitly teach the reader the correct terminology for their question. In a question asking how to build a sequence, we should state that the Python sequence data structure is a list. This clarification forms the basis of our answer and gives the reader the correct terminology to learn more.

Writing goals and principles

In order to do that we need to:

• Answer the question, and more Answer the question being asked, and the larger questions that aren't specifically being asked but would benefit a broader audience.
• Show and tell Show each solution with a code sample and tell the reader more about each solution. What's good or bad about each solution? In what circumstances would you use one solution over another?
• Write with clarity Clarity is the most important aspect of a Kite Answer. If the reader doesn't understand your solution, then it doesn't matter how good your solution is.
• Adhere to the style guide Consistency is an important component of creating a high-quality product. Read and follow the content style guide carefully so that your answer is consistent.
• DO NOT copy-and-paste from Stack Overflow We are using SO to figure out which topics need better answers. If the answers on SO were sufficient, our articles would not be needed. Do not copy text or code from SO, either directly or with minor changes. Be especially mindful of not replicating variable names, and other arbitrary elements of code samples.

Voice and Tone

Voice

At Kite Answers, we've each felt the frustration of banging our heads against a coding problem. We remember googling, reading multiple sites, trying to apply a SO solution to our code, it not working, going back to google again...And the joy of finally having someone explain it in a way that makes sense.

That's why we speak like the experienced and knowledgeable guide we wish we had by our side all the time: a favorite mentor, TA, professor who concisely answers your specific question and teaches you something more, without going off on irrelevant tangents.

We treat each question seriously. We want to educate people without patronizing them or making assumptions about how much they know.

We give people the context behind our solutions, not just the solution itself. We provide multiple solutions so people can understand how and why one solution is better than another.

This means that when we write an article:

1. We don't make assumptions about what people already know We don't skip steps. We take people through each step of a solution, and explain each step. When we use a term, we define it first. We offer links to other resources.
2. We anticipate questions We think about the additional questions that a user might ask about the topic, and answer them.
3. We speak with clarity and confidence We've researched the topic and understand it, so we can provide a good answer without hemming and hawing.
4. We use our authority to teach, not to shame We use concrete terms to describe a solution, as opposed to comparative terms like easy or difficult. We show our expertise in the usefulness of our solutions, not through posturing or self-aggrandizement.

Tone

Our tone is clear, confident, and patient. It's informal but concise. Imagine yourself in reader's seat. You're frustrated, needing a quick answer, potentially up late working to make a deadline. How can you explain the question such that the reader can quickly and easily solve their problem?

Principles of good technical writing

Avoid bullshit

Bullshit is writing that has no meaning. It adds nothing of value to the content. It exists to meet a (real or imagined) requirement of length or structure.

One of the most important aspects of...

When considering the Python programming language, one thing that frequently comes to mind is...

It can be very challenging to choose between multiple different ways of accomplishing the same goal.

In conclusion, this article has shown the importance of...

We are not a grade school, and your editors here are not your teachers. We do not care about hitting arbitrary wordcount goals, or mindlessly following rubrics for proper essay structure.

We care about providing clear, succinct answers to busy programmers. If a sentence or paragraph or section does not serve that end, remove it.

Get to the point

Most of your readers will be programmers in the middle of a programming task. They have hit a problem, and are now searching for an answer. They will often copy-and-paste the very first piece of code they find which seems to answer the question, without reading much of the surrounding material.

Articles should be written to serve this kind of reader.

The headline of an article should ask a clear question in one sentence. If the question or issue is too large or complex to be expressed in one sentence, a short paragraph should be written to explain the details.

Immediately following the question (either just the headline, or the headline plus a short paragraph), provide a brief code sample that answers the question.

After the code sample, explain the code sample as clearly as possible.

After that, explain any exceptions, alternate cases, or closely related concepts.

Provide context

If a solution relies on a standard library module or a third-party package, name it in your text and link it to the relevant documentation.

If a solution relies on an intermediate Python language concept, such as list comprehensions or generators, name the concept in your text and link to the relevant documentation or tutorial.

If you mention a topic or concept, link to the relevant documentation.

If you use an acronym, spell out the full meaning the first time.

The goal of clarity creates two opposing values:

• writing as little, and removing as much, as possible
• providing a lot of explanation

If you have to make a choice between including an explanation, and writing fewer words, include the explanation. Your editor can always remove it if they find it is too much.

Distill the question

Most questioners on StackOverflow and similar forums provide a great deal of unneeded information. This is often because they don't really know what question they are asking, or where their misunderstanding lies. (If they knew, they would have found their answer with a Google search, instead of asking a question on SO).

This makes StackOverflow questions, and their answers, cluttered and hard to read. If we duplicate that clutter and lack of clarity, we are not providing any value to the community with this project.

For example, a question about list comprehensions might include details about the asker's specific project, what data they are iterating over, why they think a list comprehension would be a good idea, things they tried instead of a list comprehension, and what other frameworks they are using in their project.

Your job as a writer is to find the real question being asked, and then to answer it.

Do not digress

Understanding any coding topic requires a great deal of prior knowledge. It can be tempting to include background information to get the reader "up to speed."

For example, an Answer about How to remove punctuation from a string might use regular expressions to solve the problem. In this case, linking to documentation about regular expressions and briefly mentioning what they are may be helpful. A paragraph explaining the syntax of regular expressions is not helpful, as it is beyond the scope of the question.

This is because your short paragraph cannot provide enough actually useful information, so it is more likely to confuse than illuminate. Provide context by naming the idea (so the reader can search for it) and linking to the appropriate documentation. Leave the rest up to the user.

Avoid judgements

Do not say that something is easy. It may not be easy for someone else.

Creating a custom exception is easy. First...

To create a custom exception, first...

Do not say "just" do something. A beginner may not know the many things required to perform a "simple" action.

Just run the script.

$ python -m script.py

If you have ever written a program, you know that you cannot tell a computer to "just do something." You have to lay out the steps methodically.

Technical writing for humans is the same.

Remove toxicity

StackOverflow is notorious for telling questioners that their questions are not good or valid.

Q: How do I...?

A: You shouldn't do that.

Q: What is the best way to...?

A: There's no way to answer that because it depends.

Q: What is the fastest (most efficient or performant) way to do...?

A: You shouldn't care about speed.
A: Try it both ways and time it.
A: That's premature optimization.
A: The bottleneck is probably going to be somewhere else so don't worry about this part.

Ignore these answers. Focus on the question being asked and the best way to answer it.

Guidelines

Addressing the user

Avoid first person

"I" would refer to the author of the article, but the articles are not written from a personal perspective.

"We" would refer to Kite (the company), but writers of these articles are not authorized to speak on behalf of the company.

Therefore, avoid the first person.

It is tempting to use the first person plural ("we") to make suggestions. Resist this temptation.

We suggest that you use a list comprehension rather than map and filter.

Use a list comprehension.

Use the imperative voice when describing what to do

Speak directly to the user in the imperative voice, rather than in the passive or third-person.

The button must be pressed.

A user should press the button.

Press the button.

Tell the user what to do, not what they can do

You can check the type of an object with type.

To check the type of an object, use type.

Use the active voice when explaining

A datetime object is returned by datetime.now().

datetime.now() returns a datetime object.

Remove modifiers, focus on nouns and verbs

Programming deals with nouns (things, objects) and verbs (actions, functions). Your writing should focus on these.

Most adjectives (words that describe nouns) and very nearly all adverbs (words that describe verbs and adjectives) can be removed without altering the meaning of a sentence.

• very
• important / importantly
• quickly
• easy / easily
• interestingly
• extremely

The exception to this is concrete or technical adjectives that cannot be avoided:

• syncronous / asyncronous
• lossy
• linked
• named
• empty
• concurrent

Assume a level of technical knowledge proportional to the question being answered

If a question is about how to get a list of consecutive numbers (like [1, 2, 3]) then assume the reader has only a beginner's knowledge of Python.

If a question is about how to know if a class is a metaclass in Python, you can assume they know what a metaclass is, and are therefore at a more advanced level.

Our answers are intended to be "quick how tos", not deep tutorials, so assume the reader understands the concepts you need to use in your answer.

If you think there will be a large gap between your audience's knowledge and what's needed to understand your answer, use a Further reading callout.