Problem

I want to include mypy as part of my CI pipeline but my existing code contains a lot (> 100, but < 500) of issues. How can I get started?

Solution

Create a minimalist configuration of mypy such that it will list issues that need to be fixed and return a non-zero exit code. Based on the problem definition, we assume that at this step you have more than 100 issues that are listed and that fixing those issues will take many hours you'd rather invest in improving the code than to fix typing issues.

Add a step in your CI pipeline that runs mypy and list all those issues. Verify that it indeed breaks the build.

Once you've satisfied yourself that CI fails, we will "fix" the mypy issues by adding the #type: ignore and/or # noqa comment after the offending lines with issues. This will have the effect of resolving all the currently found mypy issues, such that mypy should now return a zero exit code. With this, any future code that fails to pass the mypy check will break the build. This will allow you to use mypy from this point forward to check your types.

I suggest adding an additional comment such as # FIXME: TICKET-ID, where TICKET-ID refers to the id of a ticket in your issue tracking system that explains that you need to take care of this technical debt.

Always prefer to fix the issues instead of ignoring them. However, also consider whether fixing those issues is an appropriate use of your time when you want to introduce mypy (which should be as soon as possible in my opinion).

References

• https://mypy.readthedocs.io/en/stable/common_issues.html#silencing-linters

• Define the audience
• Define the purpose
• Define the assumptions
• Provide a way to contact the author
• Provide a way to ask additional questions

Question

How is value defined in a business context?

Answer

For a solution to be valuable it must solve an actual problem.

If a need exist for the solution, then the solution must do one or many of the following:

• Reduce costs/time: reduce human resources needed to produce the same results
• Increase quality: Increase accuracy/repeatability of a process
• Solve a problem that could not be solved previously
• Have a significant impact on costs for improving an already solved problem
• Offer the ability to scale the process without having to scale the necessary human support linearly with the growth of the process
• Help with identifying the most important pieces of the business in order to follow the 80/20 principle

Problem

I have rated a lot of movies on Rotten Tomatoes and I'd like to export them to a text format. I also know PHP. How can I do that?

Solution

In 2013 I wrote Rotten Tomatoes ratings exporter for the purpose of exporting the movies I had rated into a format I could read and also store.

To automate the process of acquiring the ratings, I wrote a small class which needs information available in the site's cookies once you are logged in. With this information in hand, it is then possible to fetch the ratings from the website and store them in any desired format, given that the data returned to you is a plain PHP array.

References

• https://github.com/tomzx/rotten-tomatoes-exporter

Question

What do you need to know to write good documentation?

Answer

You need to know who your audience is. You need to know what they should know so that you can make assumptions about their knowledge. You should also be able to tell what they won't know. It is mainly this lack of knowledge that you need to fill when you write your documentation.

Once you have established who your audience is, you should state it clearly. This way, readers will be able to determine if they identify or not with the target audience, which can help them better frame how to read the documentation.

The purpose of documentation should be clear. Is it to describe a specific use case, provide a getting started guide, answer specific questions regarding functionalities?

You need to state explicitly what you will cover and not cover in the documentation. Readers may start reading your document which contains assumptions about their knowledge, but if they do not have this knowledge, they should know where to acquire it.

It should be easy for readers to know where to reach the author of the documentation or people knowledgeable enough to guide them to the right people.

References

• https://www.divio.com/blog/documentation/
• https://www.sohamkamani.com/blog/how-to-write-good-documentation/