Documentation Help!

I am first time doing Big C project from the Class...
i wonder what is need to put in documentation part?.
Anyone can give me an outline please?
Thanks!!!!

:confused:

> i wonder what is need to put in documentation part?.
What documentation part?
What are you trying to document?

You can put whatever you want in the documentation. But note that adding too much documentation is wrong. Avoid describing lines, so don't do things like this

Code:

---

/* Add A and B and put it in C */
C = A + B;

---

But you can describe a block of code, like

Code:

---

/* Sort the array */

eerste = len;
for (i = 0; i < len; i++)
{
    maxindex = ZoekMax (lijst, 0, eerste-1);
    if (maxindex != (eerste - 1))
        Swap (lijst, maxindex, eerste - 1);
    eerste--;
}

---

Also useful are headers, like file-headers and function headers.

Code:

---

/* Project : <Project name>
  File    : <File name>
  Author  : <Programmer who created the file>
  Date    : <Date of creation>

  File description
  ----------------
  <Describe shortly the functionality implemented in this file>

  File History
  ------------ 
  Date        Author        Description
  01-01-2002  Shiro        Initial version
*/

---

Code:

---

/* Function  : <Describe shortly the purpose of the function>
  Param In  : <Describe input parameters>
  Param Out : <Describe output parameters>
  Return Val: <Describe the return value>
*/

Example:

/* Function  : Add values A and B, put result in C.
  Param In  : A, B
  Param Out : C = A + B
  Return Val: None
*/

---

There are many ways of documenting. Note that the style is very personal.

Besides documentation in the code, you could also write a design document in which you put your designs (pseudo-code, diagrams etc.) and explain design decisions.

Heres what I use:
Flow chart.
Structure chart.
Written description - which should contain an overveiw of the program and its working enviroment and be written in plain english, plus any limitations you have noticed. You could also add suggestons for future improvments( lets your boss know he still needs you).
Test data - show results from a known range of data, prove your program works.

The need for explaining clearly:
> i wonder what is need to put in documentation part?.
If you are refering to COMMENTING your source code, refer to the help above.

If you are refering to documenting input, or charts from the user, then you'll need to explain what you want and need.

well....documentation is wat it said on my project. my instructor said...documentation cost 75%...so i have no idea what he ask....
maybe u could help me out for reading http://cs2.bct-pcc.org/final2.htm

That's my project and i dont' understand what he want my documentation to be.

Thanks for the help and i hope u can help me a bit =>

Ok, I reviewed the site and it sounds like he is talking about commenting your source code ( professors / teachers saying documenting when the correct term is COMMENT ) anyhow...75% of the grade(?) for commenting code?

Any help here?

I'd say it's more than that.... never did programming at school, so don't take this as being right, but I'd say

- Write up what your program is supposed to do (get that from the exam paper)
- Write up how you program will achieve what is required. Highlight any shortfalls, limitations and problems. Also, highlight what benefits your program will bring that is in addition to the requirements set by the exam paper.
- Write a flow chart of how all your code hangs together.
- Write a summary of the source files, including function names and purpose.
- Highlight areas of the program you have left "open" for future expansion.
- Detail ways in which the program could be enhanced if given additional time to do the work, and show how this fits in with the previos point.
- Write a user guide. It might end up looking like a simple program to you, but the user might be a non-technical person, so an idiots guide might be in order.

- And yeah, comment your source code. Pick a style of commenting, and stick with it throughout all the source. In particular, comment the start of each function, saying what it takes as parameters and what it returns, and what it's purpose is. Don't go over board, just a line or 2 for each point is enough under normal circumstances.

Have fun!

From the site:

Quote:

---

To achieve the full 300 points for documentation, the documentation must be extrememely thorough and detailed.

---

After reading the site it reminds me of the assignments I got at university. With documentation the prof means "external documentation", not the documentation within the code, which is also important.

What profs usually want to have in the external documentation:
- An overview of all requirements, so a description of WHAT the software should do must be in that documentation.
- All designs you have made, for example UML diagrams, pseudo-code etc.
- Explain all design decisions, in other words: tell how you came to that design. Also if some requirements are not implemented, tell why you didn't.
- Provide test-cases. It must be proven that all requirements are implemented. So setup test-cases which proof that the program meets the requirements.