Comments on: The problem with documentation… http://www.noulakaz.net/weblog/2006/10/29/the-problem-with-documentation/ A blog on Technology Convergence Sat, 31 Jul 2010 17:57:34 +0000 hourly 1 http://wordpress.org/?v=3.0 By: Nadeem http://www.noulakaz.net/weblog/2006/10/29/the-problem-with-documentation/#comment-3780 Nadeem Sat, 04 Nov 2006 18:34:01 +0000 http://www.noulakaz.net/weblog/2006/10/29/the-problem-with-documentation/#comment-3780 Hi guys When i was studying for my bachelor of science course, my university always required students to get a plagiarism report from http://mydropbox.com/ for every project documentation/assignment submitted. It is a really great tool - it would be great if the university of mauritius could use this to detect and discourage plagiarism. My final year project documentation was not more than 100 pages. I believe imposing a maximum number of pages (say 100) could really make students focus on quality instead of quantity. Hi guys
When i was studying for my bachelor of science course, my university always required students to get a plagiarism report from http://mydropbox.com/ for every project documentation/assignment submitted. It is a really great tool – it would be great if the university of mauritius could use this to detect and discourage plagiarism.
My final year project documentation was not more than 100 pages. I believe imposing a maximum number of pages (say 100) could really make students focus on quality instead of quantity.

]]> By: avinash http://www.noulakaz.net/weblog/2006/10/29/the-problem-with-documentation/#comment-3578 avinash Tue, 31 Oct 2006 14:59:17 +0000 http://www.noulakaz.net/weblog/2006/10/29/the-problem-with-documentation/#comment-3578 As for your <a href="http://en.wikipedia.org/wiki/Existentialism" rel="nofollow">existentialist interrogation</a>, I am deeply sad to tell you that: <strong>NO!!!!! WE DON'T READ YOUR BLOODILY BLOATED AND DRIVEL-ORIENTED REPORTS FROM COVER TO COVER! LIFE IS TOO SHORT!</strong> :-) More seriously, I suppose this depends on the lecturer. I tend to go through reports <em>en diagonale</em> and then read only those parts which <em>seem</em> innovative and/or interesting... The thing I really despise in students reports is the Background Study when it is only a poor copy/paste job from some website or Wikipedia. I repeat myself. For my MPhil, my background study was 7 (yes, <strong>SEVEN</strong>) pages long!!! As for your existentialist interrogation, I am deeply sad to tell you that:

NO!!!!! WE DON’T READ YOUR BLOODILY BLOATED AND DRIVEL-ORIENTED REPORTS FROM COVER TO COVER! LIFE IS TOO SHORT!

:-)

More seriously, I suppose this depends on the lecturer. I tend to go through reports en diagonale and then read only those parts which seem innovative and/or interesting…

The thing I really despise in students reports is the Background Study when it is only a poor copy/paste job from some website or Wikipedia.

I repeat myself. For my MPhil, my background study was 7 (yes, SEVEN) pages long!!!

]]> By: Patrice http://www.noulakaz.net/weblog/2006/10/29/the-problem-with-documentation/#comment-3577 Patrice Tue, 31 Oct 2006 13:56:36 +0000 http://www.noulakaz.net/weblog/2006/10/29/the-problem-with-documentation/#comment-3577 some nice views by nevin i think vicks and yashvin sum it all up :) But one thing i find not nice, it that when some lecturers give away reports, they don't mention the audience and they often restrict it to paper reports! i believe it should be left to the students to be creative and also it will be nicer for the lecturer to correct something different.. One thing i always wanted to know.. Does the lecturer really read all student reports from cover to cover?? (200 pages X 50 students) :P Btw Nice blog Mr meetoo cheers some nice views by nevin

i think vicks and yashvin sum it all up :)

But one thing i find not nice, it that when some lecturers
give away reports, they don’t mention the audience and
they often restrict it to paper reports!

i believe it should be left to the students to be creative
and also it will be nicer for the lecturer to correct something different..

One thing i always wanted to know..

Does the lecturer really read all student reports from cover to cover??
(200 pages X 50 students) :P

Btw Nice blog Mr meetoo
cheers

]]> By: Nevin http://www.noulakaz.net/weblog/2006/10/29/the-problem-with-documentation/#comment-3569 Nevin Tue, 31 Oct 2006 06:32:13 +0000 http://www.noulakaz.net/weblog/2006/10/29/the-problem-with-documentation/#comment-3569 Well my point of view is not different from all of you. But i guess you all guys are interpreting things NOT wrongly but i would rather in a single direction. It's as if you are all embarking in a one way route and complaining that you cannot reverse back. "Documentation in itself at its very source is simply any communicable material such as text, video, audio, etc., used to explain some attributes of an object, system or procedure. It is often used to mean engineering or software documentation, which is usually paper books or computer readable files (such as HTML pages) that describe the structure and components, or on the other hand, operation, of a system/product." Ref:wikipedia Now we need to understand one very important point. Documentations or reports as you called them are intended for multiple users, with different background, different ways of thinking, different technical skills, different approaches to analysis, different problem understanding and problem solving skills, hence different...i'm tired already ;-) Yeps, so...hmmm....so refering to the above quote from wikipedia, we must never forget that the sole and ultimate aim is to communicate information, that is, make sure your audience or user understand what he/she needs to understand.Now since we are all DIFFERENT, there must be a way of making sure we understand what we read in a documantion. That's is why sometimes DFDs are partly presented in a report/documentaion. Understand one very important fact. What is extremely very very easy for you may not be so for someone else who may be more skillfull and intelligent than you. This is nature dear !!! :-) So to make sure they all understand, be sure that they are all 'standardized' that the role of these DFDs, etc. Even if your users are different, use these small painless techniques to regroup them under one roof. Concerning the issue of 100 pages, 200 pages, etc., my opinion is not different from yours. In fact, i suggest that the CSE department should re-consider reports writing specially for computer science students. Emphasis needs to be made on content and quality and not on quantity. ;-) Well my point of view is not different from all of you. But i guess you all guys are interpreting things NOT wrongly but i would rather in a single direction. It’s as if you are all embarking in a one way route and complaining that you cannot reverse back.
“Documentation in itself at its very source is simply any communicable material such as text, video, audio, etc., used to explain some attributes of an object, system or procedure. It is often used to mean engineering or software documentation, which is usually paper books or computer readable files (such as HTML pages) that describe the structure and components, or on the other hand, operation, of a system/product.” Ref:wikipedia
Now we need to understand one very important point. Documentations or reports as you called them are intended for multiple users, with different background, different ways of thinking, different technical skills, different approaches to analysis, different problem understanding and problem solving skills, hence different…i’m tired already ;-)
Yeps, so…hmmm….so refering to the above quote from wikipedia, we must never forget that the sole and ultimate aim is to communicate information, that is, make sure your audience or user understand what he/she needs to understand.Now since we are all DIFFERENT, there must be a way of making sure we understand what we read in a documantion. That’s is why sometimes DFDs are partly presented in a report/documentaion. Understand one very important fact. What is extremely very very easy for you may not be so for someone else who may be more skillfull and intelligent than you. This is nature dear !!! :-)
So to make sure they all understand, be sure that they are all ‘standardized’ that the role of these DFDs, etc. Even if your users are different, use these small painless techniques to regroup them under one roof.
Concerning the issue of 100 pages, 200 pages, etc., my opinion is not different from yours. In fact, i suggest that the CSE department should re-consider reports writing specially for computer science students. Emphasis needs to be made on content and quality and not on quantity. ;-)

]]> By: avinash http://www.noulakaz.net/weblog/2006/10/29/the-problem-with-documentation/#comment-3566 avinash Tue, 31 Oct 2006 04:05:12 +0000 http://www.noulakaz.net/weblog/2006/10/29/the-problem-with-documentation/#comment-3566 Exactly! As Saint Exupéry said, <em>"You know you've achieved perfection in design, Not when you have nothing more to add, But when you have nothing more to take away..."</em> Exactly!

As Saint Exupéry said, “You know you’ve achieved perfection in design, Not when you have nothing more to add, But when you have nothing more to take away…”

]]> By: Yashvin http://www.noulakaz.net/weblog/2006/10/29/the-problem-with-documentation/#comment-3546 Yashvin Mon, 30 Oct 2006 17:29:12 +0000 http://www.noulakaz.net/weblog/2006/10/29/the-problem-with-documentation/#comment-3546 well said vicksss.. we as students, if we have to return a huge report of 200 pages, its evident that in order to reach those 200 pages, we will have to include a lot of things that are just 'nonsense' including definitions, examples, diagrams instead of putting valuable and facts. for instance,lets take the final year report. just to fill in the pages, you get all kind of definitions, diagrams copied from the net, just as vicks stated. if, the supervisor clearly states that he wants only 100 pages with no blabla, then the students will take that into account when writing the report. instead of copying pages, they would rather write their own summary that would take a few pages. i really think that lecturers should put emphasis on "Quality Not Quantity!" well said vicksss..
we as students, if we have to return a huge report of 200 pages, its evident that in order to reach those 200 pages, we will have to include a lot of things that are just ‘nonsense’ including definitions, examples, diagrams instead of putting valuable and facts.

for instance,lets take the final year report.
just to fill in the pages, you get all kind of definitions, diagrams copied from the net, just as vicks stated.
if, the supervisor clearly states that he wants only 100 pages with no blabla, then the students will take that into account when writing the report.
instead of copying pages, they would rather write their own summary that would take a few pages.

i really think that lecturers should put emphasis on

“Quality Not Quantity!”

]]> By: vicks http://www.noulakaz.net/weblog/2006/10/29/the-problem-with-documentation/#comment-3512 vicks Sun, 29 Oct 2006 10:24:42 +0000 http://www.noulakaz.net/weblog/2006/10/29/the-problem-with-documentation/#comment-3512 indeed.. you are right i presume you as a lecturer you get this question very often "Sir, how much pages should it be?" i think the most important thing in writing a report is to know who will be the targeted audience and how technical it should be. last year some friends in first year asked me to have a look at their Applications development report. The problem was that instead of putting emphasis on how the system works, with different levels of dfds etc they keep on writing. "what is a dfd", "How is it important", " uses of dfd etc" The things what really mattered were not present. video podcasting will be great for our project demo Am currently having a look at "Camtasia Studio", a creat tool that records in a range of video formats whats your screen :P indeed.. you are right
i presume you as a lecturer you get this question very often

“Sir, how much pages should it be?”

i think the most important thing in writing a report is to know who will be the targeted audience and how technical it should be.

last year some friends in first year asked me to have a look at their Applications development report.

The problem was that instead of putting emphasis on how the system works, with different levels of dfds etc

they keep on writing. “what is a dfd”, “How is it important”, ” uses of dfd etc”
The things what really mattered were not present.

video podcasting will be great for our project demo

Am currently having a look at “Camtasia Studio”, a creat tool that records in a range of video formats whats your screen :P

]]>