Browsed by
Month: August 2016

Expedition in search of good documentation

Expedition in search of good documentation

Some time ago I saw an information about new StackOverflow section named Documentation. At the very beginning, I was very excited about this new feature. It sounds great to structure and organizes all the knowledge contained into this portal. Every day thousands of developers contribute to growing this one of the world’s biggest knowledge base. It is a great goal to achieve. However, when I started to look carefully at the content and the form of the knowledge in this documentation I realized that I even don’t know what good documentation means. So I decided to start my journey in search of good documentation.

Why we create documentation?

At first, we have to consider the most important question. Why do we need to bother about documentation? There are two cases:

  • writing a library that other developers may use
  • developing a regular application

We can easily see the difference between these two variants, but the case of documentation they behave almost the same. If we consider that every part of application code need a maintenance, we can say that we write every project for other developers. In some cases, the other developers would be – we some time later. However generally we can assume that independently from the project purpose, we should store our knowledge. It is important especially if we decide to create some custom components – without following to some standards. That kind of documentation should be a great help when a fresh person wants to use it or modify it. It can be also the first place to search business assumptions used in the project.

Who wants to use documentation and when?

Based on the above purposes of creating documentation we can identify 3 personas that may want to use documentation:

  • future me – when we need to make some modification after a year of work in another project
  • fresh developers in the team – when they need to hop into the project and start developing
  • users of our project – when we creating a library of API available for other developers

We focus only on technical documentation here but on the last point we can also include business user documentation. On the other side, API documentation is a bit different subject so I will describe it more detailed way later.

What documentation should include?

This is not an easy question. It mostly depends on our audience and purpose. However, we can definitely select some elementary components.

  1. Instruction to install or start working
  2. Definition of convention in use/contribute
  3. How to use project functions
  4. How to contribute/extend

I know exactly, that this list don’t exhaust all variety of the most important documentation component, but they are definitely the most common ones.

What are the qualities of good documentation?

I reviewed much documentation. Many of them, I also used in my developer’s experience. Based on this knowledge I can specify some main characteristics of usable documentation.

Searchable

We do this all the time when we want to use documentation. We should be able to search all necessary information as quickly as possible. Generally, we can say that this is the most important functionality for documentation. It can by achieved using regular search functionality

or well-organized table of contents

Provides quick start section

Good designed documentation should be able to help users with different level of knowledge. We should provide a starting easy guide for people who try to use our product for the first time. It is very important to not putting barriers in learning for newcomers.

Documentation should also contain a description of some common parts in the application. For example, it should precise how to handle errors during the use of library and methods to authenticate. All these side notes are very dependent on the context of the project. This is a subject related to typical, common users questions.

Examples

The last, but definitely not the least one characteristic of good documentation are examples. It helps to see how to use some feature in user code. It also enables a way to understand the behavior without writing the function on your own. Especially when we are able to run them straight from the documentation. Examples remove an abstraction layer hidden behind the pure documentation text.

Different approaches to documentation

At the end, I want to share with you, my list of the best documentation which I know

Kendo UI Grid

It contains a good search component and well-organized index. It also has many examples, that we can execute in the browser. Very usable and fast to use.

Aurelia

The same as the previous one has great search and good technical documentation. It enthused me with guides section, that contains a set of general articles depending on your role. You can define that you are a developer or manager and read the guides designed specifically for you.

StackOverflow Documentation

The newest one but the most promising. It is a documentation created by the community, according to the community needs. It has a lot of examples and lives demos in popular subjects. I will definitely follow and contribute to this project in the future.

LESS

The example of quite simple documentation, but very efficient. In fact, in contains all necessary information in the minimalist form. It could only have better search mechanism to tell that it is one of the best.

Knockout.js

Similar to LESS documentation. Very simple and clean. The one distinguish a feature is a form of structuring the subjects. All documentation is written and organized as a story starting from the installation to more advanced functionality.

You can find a good description about creating your own documentation here: https://www.sitepoint.com/products-documentation-good-enough/

Cover photo

How I broke WordPress site

How I broke WordPress site

For the last two months, I was taking a little break with writing a blog. I wanted to finish writing my book and close some other projects. I succeeded. I also have an idea to use this time to work a bit on my blog. I decided to move it to another hosting server. That my adventures begins. I installed it on the new server and migrate all the content. The deciding moment was changing in the domain configuration. The only things that I needed to do are: change DNS addresses and WordPress address in its configuration.

What can goes wrong in this scenario?

I found it out very soon. I made a mistake in WordPress address.

Then I try to move to some other configuration option and the page fails to load. It appears, that every link on my site direct to nonexistent address.

“Oh no”, I thought, “all the work for nothing and I have to start from the beginning”. However, after some search, I find out that I can still fix it. Generally, I have 2 options to do it. I also found how I should do this migration to not worry about mistakes.

Edit wp-config.php

These two variables can be defined directly in your wp-config.php file. It contains all local configuration of your WordPress and can have also these variables.

define('WP_HOME','http://example.com');
define('WP_SITEURL','http://example.com');

However, at the beginning, it doesn’t contain these variables defined at all and you have to add them to file.

Edit in database

The other method to fix this problem can be done from the database level.

Table wp-options contains the same configuration variables that can be defined in file wp-config.php. We should change the values of rows with the name: siteurl and home. You can see that is is the same names as for PHP file.

How I should do this

At the end, I discover how we can enable a special mode to migrate your WordPress site. It has a name: relocate mode.

Setting a parameter

define('RELOCATE',true);

into wp-config.php file let us enter the relocate mode. It ensures that siteurl variable won’t be taken into consideration during page generation. Address that led us to the main page will allow us to operate within the administration panel. This option is limited only to the administration panel. The regular blog will not work if we made a mistake, but we will be able to correct it from WordPress configuration.

We should remember to disable this relocate mode after our maintenance work.

That is an easy way to break a blog, stress a bit and finally fix it.

[mc4wp_form id=”510″]

Photo source