negezor/srcds

Source Dedicated Server toolkit

srcds's Issues

Lack of documentation

Why is the lack of documentation bad?

It is always a good idea to remember that not everything in a procedure or module was designed in a perfect world. Programmers make many mistakes and there are rarely proper tests for everything. Some of the more annoying examples of that is the lack of documentation. There are some tasks that may not be documented because the developer didn't think they were important or useful. Such tasks may be skipped entirely. What if you are working with a help function that doesn't have documentation for that purpose? The problem with that is that you might skip some really cool functions because you didn't have a specific function to use. Now you are at a dead end and have wasted your time. These are situations where it is necessary to document things. It doesn't always have to be in the same document. It can be in a make-work document that your team is building to solve different challenges.

What should be documented?

We have reviewed a number of modules from Magento for this series, with good results. However, in most cases the documentation should not be one of the things you choose to optimize. In some circumstances, it is a good idea to include some tests in the documentation. Tests are much more reliable than a simple write-up. Also, tests can become a record of how the module performs. That makes it easy to determine how to use a module to satisfy your requirements.

One thing you will want to ask yourself is "How do I save time?".

How do I save time by writing less documentation?

Sometimes there are really simple tasks that can be replaced by a single check-in. When that happens, it is a huge win. In such cases, you can skip the documentation completely. This is the case for many of the pre-setup modules. You can configure a pre-setup module very easily, and you don't need to write documentation for it.

Even though I still consider documentation as a must, I think it is best to focus on speed.

In a world of massive software projects, where everyone wants everything to be the best, it is difficult to move forward with slow-moving documentation. Let's see how the best developers create massive software and the most modern developers still document their modules and scripts.

In the world of the modern developer, it is not unusual to spend hundreds of man hours trying to keep up with software documentation. In the end, the documentation slows the development process and hurts the user experience.

One way to save time and reduce the cost of documentation is to get it right the first time. Document everything you do and don't do, and then update it if necessary.

Some of the best developers write all their source code. It is up to you to determine how important documentation is to you. If it is not important to you, you can skip it. If it is extremely important, but you haven't documented everything, you can add code tests to make sure you cover all the bases. In other words, you will be testing more than documentation.

My favorite developers document everything. That is because they treat documentation as an asset that they want to be sure is in the hands of the next generation of developers.

In the final analysis, documentation and testing, in combination, are the only way to move forward.

Let's take a look at some of the things I have tried.

On the plus side, I have written a lot of automated tests. Most of the documentation is not testable because it is very complex.

My own personal tests haven't worked all that well. They have errors that are hard to fix. The module I use for testing still requires a manual test.

My testing is fairly specific to this module. The tests are an essential part of the process, but not an essential part of the documentation.

With my tests, I can report something like this:

it('should return true', (t) => {
  t.is(true, true)
})

That's great, is it?

Here's another approach. I used to write a document called Magento source code guide. I called it this because it was designed to be a source code guide. When I had some experts help me in improving the documentation, the guide evolved into a well-crafted manual. I learned that this was much more useful than the guide.

I think if I ever wanted to write documentation, I would start with a source code guide. This is the same reason why most software developers write code, write unit tests, and document the code. The goal is to document the code so that another developer can build on top of it.

I used the guide in my best project. I would probably never write another Magento module without writing the guide first. In some cases, that documentation can be very difficult to understand. Some people who write code aren't great at writing documentation.