25 Feb 2020

Knowing your users

History / Edit / PDF / EPUB / BIB / 2 min read (~314 words)

What should I know about my users if I want to build appropriate software for them?

If you are building technical software for your users, you need to know what their level of expertise and experience is. If you can use a job title to describe their position, that is a great start.

You should define the users' strengths and weaknesses, that is, what you expect them to excel at and where they will require more of your assistance to succeed at their task.

Define the scenarios in which your users use the software you will build. What information do they have available? Which information do they need to gather? What kind of decisions do they need to make? Which decisions can be automated for them? Do they need to run the software in a specific environment? Do they need access to data to do their task? How is this data made available to them? When do they use the software? How frequently do they use the software? How much of their time is spent on the task they are solving using the software you're building?

Define what the users' goals are. You might be creating a text editor, if your users' goal is to transmit information between companies, they may not care at all about making the text fancy but they might appreciate your editor helping them correct grammatical mistakes.

You want to be as specific as possible when describing your users so that your decisions are guided by this persona you're creating. What kind of company are they working in? Startups, PME, large enterprises? Do they have multiple responsibilities or are specialized?

With all this information about your users you should be able to make more judicious decisions. This will help you scope your work.

24 Feb 2020

Writing documentation

History / Edit / PDF / EPUB / BIB / 1 min read (~23 words)
  • Define the audience
  • Define the purpose
  • Define the assumptions
  • Provide a way to contact the author
  • Provide a way to ask additional questions
10 Feb 2020

Working on the most important task

History / Edit / PDF / EPUB / BIB / 1 min read (~165 words)

Why aren't we always working on the most important task?

For bad reasons:

  • We don't want to work on the most important task.
  • The most important task feels overwhelming.
  • The most important task seems too risky.
  • The most important task doesn't seem fun to work on.
  • We want to work on fun tasks, not hard tasks.
  • We want to work on what interests us, not what provides the most value.
  • We think that the task we're working on is more important, but it isn't.
  • We don't know how to solve the most important task.

For acceptable reasons:

  • We don't know what is the most important task at the moment.
  • We don't understand what is important to our clients.

For good reasons:

  • The most important task has prerequisites that need to be completed before it can be done.
  • The most important task is being done by someone else already.
  • The importance of tasks is likely to change soon due to a change in objectives.
10 Feb 2020

AST in python

History / Edit / PDF / EPUB / BIB / 1 min read (~193 words)

I want to analyze a python script to extract something from it. How do I do that?

Python has an abstract syntax tree like most programming language.

You can use the ast module to parse a string that contains the code you want to analyze.

A simple example is as follow. It will read a file defined in the file variable, use ast to parse it, returning a tree that can then be traversed using the visitor pattern. Defining visitors lets you separate the responsibility of each of them, making the code that analyzes code easier to understand.

import ast

class ClassVisitor(ast.NodeVisitor):
    def visit_ClassDef(self, node):
        # Do some logic specific to classes
        self.generic_visit(node)

class FunctionVisitor(ast.NodeVisitor):
    def visit_FunctionDef(self, node):
        # Do some logic specific to functions
        self.generic_visit(node)

visitors = [
    ClassVisitor(),
    FunctionVisitor()
]

with open(file, "r") as f:
    code = f.read()

    tree = ast.parse(code)

    for visitor in visitors:
        visitor.visit(tree)

09 Feb 2020

When to abandon pull requests

History / Edit / PDF / EPUB / BIB / 2 min read (~224 words)

When is it appropriate to abandon a pull request?

Assuming that this is in a business context, you should abandon working on a pull request if getting the pull request merged is taking away too much time from others and it requires a lot of additional changes, creating a lot of back and forth between the creator and the reviewers.

You should abandon it if the feature/bug it fixes is not important enough compared to other more important ones. One should always work on the most important task rather than to work on tasks of lower importance. Furthermore, working on low importance pull requests will also "force" your coworkers to review those low importance pull requests, reducing the overall productivity. As such, always think of the impact you will have on others.

Many developers often think that bugs are of the utmost importance and should be fixed as soon as possible. However, implementing a good fix might require a lot of effort on the part of the person that will fix the issue, as well as a good amount of effort on the part of the reviewers which could have spent their time on features or bugs that are more important. Like anything else, bugs should be prioritized based on how important they are, not just that they are a bug.