We did the SDLC in Chapter 42. You might have remembered me mentioning that each stage comes with some sort of deliverable, which is also referred to as documentation. Documentation is a set of notes that explain how something should work or how it should be used. In this post we will be walking through various kinds of documentation so that you will know what you need to write for your coursework which is loosely tied to the SDLC.
Program Documentation
Program Documentation refers to all notes that explain in detail how a particular implementation of an algorithm works. These notes are technical in nature so they are normally used by people, such as programmers or system architects, who can understand code and algorithms.
Since computational thinking is a big part of this course we have gotten into numerous ways on how to describe algorithms in Chapter 50. Allow me to give you a quick reminder here:
Any piece of work that describes an algorithm is program documentation.
Source Code
Your teacher has probably told you during practical session how important it is to:
It is also important to mention that the automated tests are part of the source code. In fact, unit tests similar to ones you did in practical sessions are an essential part of the program documentation.
Before a new feature or bug fix can be tested by staff and potential users developers should provide a report that all the automated tests pass! Below is a simple example of a test report for a single feature so that you can get an idea:
Technical designs in the form of flowcharts or pseudocode
Flowcharts and pseudocode are explained in detail in Chapter 51. Only the most relevant information has been extracted to jog your memory:
User Documentation
When people buy a digital device such as a laptop or mobile it always comes with a tiny booklet which normally contains instructions and diagrams on how to operate the device. This is formally referred to as user documentation. You might find it interesting that web applications also have user documentation that describe features and how to perform certain tasks.
Really good design requires little explanation usually however companies still go through the trouble of creating a user manual. In fact, a very popular social media platform, Instagram, provides an online user manual here. If you check it out you will notice that it has very simple to follow instructions with screenshots of the application so that the user can find it easy to follow.
Below is an interesting video by a company that makes templates and it clearly explains the process of designing a beautiful user manual.
Technical Documentation
This one is a bit tricky... because it kind of sits in the middle between program documentation and user documentation. In fact, technical documentation is intended for anyone who is interested in how a digital product has been built and how it can be used.
Technical documentation differs slightly from program documentation because it is intended for people who are not contributing to building the product, but simply using it. It describes how something is designed; how it should to be used and perhaps specify requirements in order to make use of the product or service. Here is a list of scenarios that perhaps you might understand:
When anyone buys a computer they probably want to choose certain specifications like the amount of memory it has, the type of graphics card, the power of the CPU etc... A good example is looking at the tech specs before buying the latest iPad.
When anyone wants to install an application on their phone it is important to indicate whether their device is compatible with the installed version of the operating system. A good example is looking at the the system requirements to install Duo Lingo.
When programmers have made used of a plug-in that was built by someone else, and for some reason it is not working as it should, they might need to read instructions on how to troubleshoot the problem.
Comments