1

I am writing the documentation for a piece of software which I have made but I don't understand what it means in some aspects.

It asks me to write about backup procedures but what exactly does this mean? Does this mean like backing up the database on another hosting service or something else entirely?

I am dumbfounded by what troubleshooting guidelines are as well.

If you have any idea what this could mean feel free to give your insight even if you aren't 100% sure in case it could spark what it means inside of me. Thanks.

2

What you're asked to do is, I believe, describe (1) what would happen if something wrong happens, and (2) how to react when it happens. The official term is disaster recovery plan, but I assume they call it "backup procedures" and "troubleshooting guidelines" in order to be more specific.

Backup procedures

Imagine that I, as a customer, am working with your software product. I may have:

  • Files which I stored in a location I've chosen,

  • Data which is stored by your application, given that I don't have to know where this data is saved,

  • Configuration.

Backing up the files is generally the responsibility of the customer, since they are separate enough from the application. I may have Microsoft Word files that I open sometimes with Word, sometimes with Open Office, and sometimes with my custom-made app which extracts some information from them. None of those apps should be responsible of those files, since none own them.

Data, on the other hand, is strongly related to the application itself, and the user doesn't have to deal with this data directly. It's up to the application to keep this data safe, eventually with the help of the user. Configuration is in the same category. It's the same data, but more specific and even more linked to the application.

Scenarios

Imagine the following scenarios:

  1. My hard disk fails. What happens? I may have baked up my files, but what happens with the application data and configuration? Do I have to reconfigure everything? Or was your application helpful enough to back the data up somewhere (in a cloud service or in a location I've chosen and that I baked up together with my personal files)? Would it be clever enough to recover all my settings?

  2. I want to migrate to a new PC. Do I have to redo all the configuration, or the app is smart enough to let me back the data up in one click, and restore it in one click later?

Example · Adobe Lightroom

If you have used Adobe Lightroom, photos themselves (RAW/NEF files) would be in the first category, the catalog will be in the second one, and templates will be in the third one.

While I have to deal with backing up the photos themselves, I shouldn't care about the catalog, and even more about the templates. Lightroom does a good job of backing up the catalog (by providing a choice every time I shut the application down), but does nothing to backup the templates. Adobe's website specify the location of the templates, but it means that when I have to migrate it from one machine to another, I have to copy those files manually. Dealing manually with the photos, the catalog and the templates is not the best user experience I would expect from such product, and while I expect to have to protect my photos myself, a one-click backup solution for both the catalog and the templates would be welcome.

Example · Google Chrome

Chrome has a different approach. When using the sync feature, it bakes up the bookmarks, the entered passwords, the list of extensions, the browser settings, etc. on Google servers.

This approach would be problematic for a software product such as Lightroom, because I don't want my 500 MB catalog to be synchronized with Adobe's servers each time I change it (I have an impression that diffs won't work for that). On the other hand, this is a particularly elegant approach for software products such as a browser, a word processor or even NVIDIA Control Panel where I pick the options for my GPU.

Conclusion

In a document which describes backup procedures, I expect to read:

  • What needs to be baked up in order to become operational as fast as possible after the loss of all information except the backups,

  • How easy/difficult is to make backups for an end user,

  • Is there a scheduled backup, and if there is, what's the frequency,

  • How to automate the backup procedure (and eventually the recovery procedure as well),

  • Is my data safe, if it's stored in the cloud (I certainly don't want Google to have my Amazon's password stored in plain text),

  • Are there scalability issues (Lightroom catalog takes less than a second to back up when you have a few hundred of photos; with dozens of thousands of them, it may take a few minutes),

  • etc.

Troubleshooting guidelines

This is rather the description of any issue which may happen with your piece of software. For example, what happens if it runs out of space? Would it crash, or would it, instead:

  • Alert the user that the PC is running out of space a few hours or minutes before it occurs, and:

  • Later, alert the user that now, the PC is out of space, and either gracefully shutdown if there is nothing unsaved, or keep running and ask the user to free some space to save the data, or chose a different location.

In the same way, what would happen if there are network connectivity issues? Or any other issue relevant to your specific case?

  • Thanks for the in-depth answer it really helped me write the piece of documentation with a much more solid understanding of what was asked of me :) – Podolski May 31 '14 at 17:04

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.