085400100003 Programming standard DOCUMENTATION

085400100003 Programming standard DOCUMENTATION

Documentation is the document about the program

Table of content, images, sometimes diagrams, version of the document and path where to find it whe you only have a hardcopy.

Most poeple document after the program is done, but it is a bad idea because most of these poeple dont have the time or the budget to do it after. (or the will power)

So you have to document as you program. To do that, start the main document the first day you start writing code. The document will be very strange and full of things you will not need later. Because of this, lt's assume the first docuement is a log of what the program do, or what you intend to do with the program. Kinda of a log of your actions and plans.

When you are at the step of doing the real document, you will have this first document as notes to compose the real thing.

The document is not the the program diagram. It's something everyone can read to use the program.

So first, it will have a small definition of the words needed to understand the document (computer science is not known to everyone, use regulard language as much as you can)

I know some poeple will not agree with using common words to explain complicated stuff, thoses poeple, ignore them, no one understand them anyway.

So if you are about to say use the term "DB" in the document, then use database. And if you use database, then define it in the first part of the document as "a serie of tables related to each others with some identification number".

Some will now say my definition of database is not the right one. Well, they might have to learn that not everyone is a programmer. Just as they might not understand the mecanic repairing their car. Everyone have a domaine of knowledge in wich they excel more. And know more. The person reading your document might not know all the terms invented recently by internet.

Try to do short sentences. If there is too  much text, no one read it. It's called pollution of information. A polluted document is not readable or very long to read.

Add images of the screens from the program. I know, images are big! So what? Some poeple like visual input. It's hard to find the button "options" when the person doing the documentation forgot to say it's in the edit menu. The image will show that.

Checklist:

1. Table of content, version, path to document

2. Word definitions for computer science words. example: database.

3. Short sentences. Do not pollute the information.

4. Images for the menus and sub menus.

5. Start your document at the first line of code or else you might never do it.