Why does authors write nonsense and why are we tested on their nonsense?

Dear Unisa Lecturers and Fellow Students

Last year I completed my Bsc.IT (software engineering stream) at Unisa.

Throughout my studies at Unisa I have had various courses with books full
of inaccurate statements and facts - opinions given as facts in books by authors.

I just stumbled upon another example in our prescribed book for IN417-N - on page 115 under 4.7.
The author makes the following statement about open source software:

"...documentation of any kind is extremely rare...."

Open source products are probably the best documented software out there, take for example
the Linux manual pages:

1. Available on every installation by typing "man topic"
2. Available on the Internet in various forms - html, pdf etc.
3. Using any, and I mean any search engine you can find hundreds of sites with documentation about
almost any Linux or open source topic.
4. Further the developers e-mail addresses is often listed on the project sites - you can actually contact them.
5. No closed source project I have seen comes close to this level of documentation.

Now in view of above facts (not opinions), I would like to ask the Unisa lectures the following two questions:

1. Why is there almost never errata in the tutorial letters stating that point x, y and z is wrong in the text book.
2. Why are we asked questions about these false statements in exams and assignments, and then expected to give
an answer similar to the author's - that is, one that is also wrong.


Fellow students, please comment on this as this is my experience - yours might be completely different.

Are they not talking about design and requirements documentation ?

You can argue that they are talking about the design and requirements documentation, you can even take it further into specification documentation, because specification comes after requirements and before design.

Here we can pause and say, does the open source man pages, websites etc not list what the application was written for (and they mostly do this in detail) - thus requirements.
Do they not almost always specify what the features and objectives are? what programming language was used? what graphical toolkit was used etc? - thus design and specification.

One can take it further, does the documentation not often include reason's why features was added and removed? Along with future directions and plans - Documentation that is crucial to post delivery maintenance.

Even more so, is a manual not a combination of requirements documentation, specification documentation and design documentation? To see this, think of a manual, it tells you what functions/use of device/program/product is provided (inspired by requirements), it shows instructions (which is ruled mostly by specification) and how the interface and works ( directed by design).

Open source relies more on documentation than any other methodology, documentation is one of the strongest and best used communication channels used by open source developers. Look even at forums which contains discussions about open source developments - even this is available, the communication between developers, as is, in context, not watered down minutes from a meetings by a secretary that does not even understand the concept of object oriented programming. Further the documentation is available, anywhere, anytime - not like closed source software where documentation is often safe guarded and difficult to get your hands on.

Quality and impact of documentation - Do want a manual written by someone who only does it in his 9 to 5 job, to survive, or by someone who has passion for the project? Which is going to be the better manual? documentation in other words?

I state again, we pay more than enough money for these books and study fees, that there should be proper errata for stupid statements. I have the same type of problem in another subject, where the lecturer does not even respond on e-mail - after I sent him the same e-mail 3 times. The quality of our education can improve by at least 10% if confusion caused by incorrect statements are removed. If our education improves by 10%, imagine how much of an impact this can have on all of life???

Dear Student,

The nature of this module is experiential. Software Engineering is not an exact science and hence this module is supported by articles to give you differing view points. It is not expected that you reproduce points of view from the prescribed text without a critical evaluation.

Kind Regards,
Dr K Padayachee

Quote
jlc
Do want a manual written by someone who only does it in his 9 to 5 job, to survive, or by someone who has passion for the project? Which is going to be the better manual? documentation in other words?

While you and I might want a technical manual, we are far from typical users.

You are then assuming all documentation concerning open source is purely technical......I have to disagree....When I read your comment, I looked around me in search of the first piece of open source software I could find....an Ubuntu Linux installation...I clicked on the app menu, typed "he" and "help" was the first option that came up, i clicked on it and found user friendly documentation.....not only was it user friendly (verified by two other non-technical people in the same room), it was also complete. Steps-by-step instructions, under easy to find categories, from how to setup e-mail, how to change background, how to "ANYTHING" - step-by-step - go and read it, it is awesome, it is clear, easy and it works! Every day task was highlighted and placed at the top.....someone with no technical experience can setup their e-mail, wifi etc with this guide.....try this with other products.....

Sure there are open source products whose documentation is not as good, but most closed source documentation does not come close..

Now walk to any closed source product and compare......

My point still stands....the author does not have a clue what he said about this.

Software Engineering is not as much as a experimental subject as a developing subject - experimental means it is being tested, this subject field has been tried and tested and thus it's existence, it is a field that is growing faster and faster each day.....but we, the students who want to help take this field further, has to sit behind our desks and read non-sense. If I could count the amount of times the author repeats his 4 or 5 opinions/facts on this field, i could probably predict the amount of pages in this textbook by means of multiplication.

How about we do some software engineering....let's discuss the best searching algorithms and how to customize them, lets look at encryption techniques....in detail. We are reading what encryption is....we passed a Bsc IT degree, but can we write a proper encryption tool, we did 30 modules of which about 25 told us about encryption and advanced coding etc...but how many thought us these techniques.???? none, because we have to sit and read crappy textbooks, so we can.......nothing!

Software - the subject area, Engineering - the discipline, what we are doing is more like "Software - How to hide that you know nothing".

A discussion regarding the best searching algorithms should be reserved for a course on data structures, and encryption techniques in an information security course. A BSC isnt about teaching what you need to know when entering the job market. If that is what you want, you should have done some industry certifications and you would have been done in a few months. A BSC is about knowing what is out there, understanding the fundamentals, knowing where to find more information, and using the things you have learnt to understand whatever it is you wish to understand. It is not possible to give a person all the knowledge they require. One of the main things you learn at university is that you know very little.

Certified courses equip people with knowledge to implement current technologies. Ask one to discuss things like data structures or encryption and their knowledge will be limited at best. I have worked with both Comp sci graduates as well as short course programmers, and the CS graduates are generally much better at understanding things like algorithms and such. Not only this, but if they do not immediately understand it, through their own investigation they are brought up to speed quickly. In comparison the 2min programmers flop.

experimental <> experiential

Scaq: You are taking an aspect you have something to say about and then running with it, although you are fairly right in what you say, it does not pertain to the discussion. The discussion started with author writing nonsense and then we having to accept it as learning material. Then in the course of discussion I merely gave examples , clearly bad examples which did not convey my message. Thus I want to apologize for the bad examples and thank you for explaining to me what the purpose of my degree is - Yes, it seems that Scaq, thought it may be necessary to tell me, what the purpose of my degree is - after me completing it...Scaq my apologies if that sounded sarcastic...


I will once again make my point: I have shown one case out of hundreds during my studies, where I have found textbooks to be inaccurate or almost useless. This is not mentioning the hundreds I have missed and other students picked up. We pay lots of money for these books, WE SHOULD EXPECT THEM TO BE ACCURATE. The second problem is the lack of tutorial matter correcting such problems, lots of these books has been used for two or three years - surely a lecturer can say: Ignore point x on page y, replace it with z. Or even, mmm, this is a bad book, let not use it - the book in this module is not that bad, but there has been more than a couple for which this has been the case.

Nanthu: Thanks for the correction, I did miss that at first(My speed reading clearly needs some work....), but my point still stands.

The actual authors of these books are usually easy to get hold of, and usually love it when a student who has had their book prescribed speaks to them about it. Perhaps you should take it up with the author?

@JLC: Forgive me if I went off topic, but you were the one who wanted to learn about DS and encryption in a software engineering subject. Unless you were generalising.

With respect to incorrect information, I try not to use what I have seen as incorrect in any answers to assignments or exam questions. Your initial example is one such thing I avoided using in the last assignment.

I believe the miscommunication here is founded on a generalisation made by the author. I would even go as so far as to say that, it is he's general finding and thus opinion that open source software lacks documentation. I myself have had experiences where adequate documentation was lacking in some open source software. This does not mean that this holds true for all such open source projects. You need to remember that the author is also human and we have paid for his analysis and expertise on software engineering. We did not pay for a 100% accurate handbook (I doubt you will find one in exsistance). Instead of blasting the author, perhaps it may be more constructive to engage the author on this point so that the next revsion published may have a different perspective.

Schach is pretty much a CSS fan - and takes every opportunity to bash OSS.
I did this module in 2010, and said as much in the exam when I had the chance, and still got a distinction!
In my opinion, argue against schach if you want, just make sure you back it up.

My own favourite is an article by Schach that talks about Linux and its coupling problems, but he does not discuss CSS in the same way - he just alludes to the fact that OSS must be worse. The elephant in the room is of course that he cannot have had equal access to MS Windows source code, so how can he make any such claim (implied or not).

Just enjoy arguing against him, it is educational at least.

> The author makes the following statement about
> open source software:
>
> "...documentation of any kind is extremely rare...."

Once you have spent enough years working on many kinds of software, you will find this statement to be true.