Welcome, Guest. Please login or register.


Author Topic: Importance of documentation (Read 12622 times)

Offline Tuby128

  • EP addict
  • *
  • Posts: 1449
  • Country: hu
Importance of documentation
« on: 2013.February.22. 17:33:05 »
Mr Tanner,
 I have an interesting question to you. But first, I have to tell the background story.

 A few years ago, when I still went to the university, I had an old and well experienced teacher, who's speciality was the security systems by the national and international train systems. He was about 80 years old. A well educated, well informed wise man, with a good sense of humor. He could speek at least abour 4 languages (I heard him speaking French:)). As we listening him, about the stories installing a train-controll system in the North-African countries in the 60s and 70s, I realised that he lived through many things, and that's maked him so noble engineer.

 Well, one day he told us about disasters, and he gave us a good advice. "You should always have a diary or notice-book, which always contains information about your work. For example, if you are a building-architect, and design a new bridge, make a notice what kind of standards did you use and why, because if something goes wrong, and you are in court, people never remember the important details, and maybe it can destroy your later carrier."

 This thought was really new to me. I think it is applies every part of an engineer's life. I remember before, I never made any plan, before started to do programing (or build a new electronic system). That's why sometimes it took a more time to perform the task. The another problem was the lack of comments, and registering failure experiences. (Maybe I can call that documentation.)
 In my oppinion, the another important thing is the reusing an already done work. (By the way, I know that in the z80 Era wasn't there position-independent instructions, no wonder why people start writing from the ground up).
 My standpoint is, documentation is a very important task, in spite of when it took more time to accomplish the entire work.

 My question is, what do you think about that? (I know, that time you wrote the Basic and another extension, you had to hurry. I did't mean you. I talk about this topic generally.)
« Last Edit: 2013.February.23. 09:22:33 by MrPrise »

Offline BruceTanner

  • EP lover
  • *
  • Posts: 607
  • Country: gb
Re: Importance of documentation
« Reply #1 on: 2013.February.22. 19:12:16 »
Hi Tuby128,

You raise some interesting questions, and it is difficult to argue against documenting things well and keeping records. The first point I would like to make is that if you use such a note book in the course of your employment, the note book would belong to your employers and in a case such as the collapse of IS it is likely that I would not have access to the note book afterwards (by the way I did not keep such a note book,but I have known hw engineers who have). The second point is that a bridge or building is much more safety critical than anything I have ever worked on and you would hope that everything is well documented. Of course safety critical software does exist eg. In medical equipment and you would hope that is well documented too. The third point is plenty of bridges have been designed in the past, so you know how to design one that is safe because people in the past have made all the mistakes.

Regarding comments in code, in my opinion quality is just as important as quantity. So often I have seen eg. "INC A ; Increment A" - a comment yes, useful no! I have heard of automated tools that attempt to rate the quality of software by the ratio of lines of code to number of comments. And also of tools that automatically generate comments of the sort above in order to get a good rating! Comments need to say why the code is doing something, eg "INC A ; Because the coordinates are 1-based not 0-based".

I also think it is important to allow flexibility while developing. Sometimes you only know the best way of doing something by doing it a bad way and learning from that. It is my experience that a good programmer can write something the second time far quicker than then first time, and should not be afraid of doing so. In English there is a saying "If it is not broken, don't fix it". A very good programmer I used to work with used to say "If it is not broken, break it" [because you will rewrite it much better].

In the case of the Enterprise software, the specification was the BASIC syntax and a general list of things it had to do (eg have an editor and joystick, be expandable). We were pretty free to decide how to implement those features. Documents such as the EXOS function calls were written along with the code and evolved with the code. The code was pretty well commented.

I say all that with much more age, experience and hopefully wisdom than I had back then and I would be the first to admit that the Enterprise software project could have been better managed, particularly regarding setting deadlines and hitting them! But I did not know that then, aged 19 or 20, and the management of the whole project was not in my power anyway.
« Last Edit: 2013.February.25. 09:18:34 by Zozosoft »

Offline Tuby128

  • EP addict
  • *
  • Posts: 1449
  • Country: hu
Re: Importance of documentation
« Reply #2 on: 2013.February.22. 19:56:00 »
Ok, now I know what were your abilities and what weren't at that time, when you were at age of 18-20. How did things changed by you during the time? Can you now presage the accure deadline of a sw project, and can you better manage yourself? It would be great, if you tell me perhaps some concrete example from your latter life. (As I said before, I am a very curious person. :) ) The IBM's token ring is an interesting theme, there would have been some trival problems, which made you some unpleasant difficulties.


(By the the way, you have to know, there is people (mostly Hungarian people) in the forum, who cannot speak English so well to start a dicussion with you, but really interest about you and your work, and this is a very good oppurtunity to use their English knowledge. At least when they're reading your posts.)
« Last Edit: 2013.February.25. 09:18:42 by Zozosoft »

Offline BruceTanner

  • EP lover
  • *
  • Posts: 607
  • Country: gb
Re: Importance of documentation
« Reply #3 on: 2013.February.22. 20:43:57 »
The first concrete example was actually very soon after...TVC BASIC in fact. IS had employed a project manager by then and I remember having to estimate the number of days for each part and indeed it was done on time. I imagine the contract between IS and Videoton probably had stiff financial penalty clauses for late delivery!

I hope I can estimate project times much better now...I think that comes with experience. It becomes much more complicated when several different people and hw production are involved in one project. We used to have a rule (humorous) that everything takes 6 months! But there is a little bit of truth in that...if it's much shorter, it's not worth doing as a separate project, and if it's much longer it'll be out of date before it's released (now where have I seen that before...;-))

I am trying to keep my English fairly simple so people have a chance of understanding it, and also so Google translate has a chance!
« Last Edit: 2013.February.25. 09:18:51 by Zozosoft »

Offline Zozosoft

  • Global Moderator
  • EP addict
  • *
  • Posts: 14733
  • Country: hu
    • http://enterprise.iko.hu/
Re: Importance of documentation
« Reply #4 on: 2013.February.22. 22:20:35 »
Quote from: BruceTanner
Documents such as the EXOS function calls were written along with the code and evolved with the code.
These are the Technical informations?
The user manuals (BASIC, FORTH, EXDOS, ISDOS) is also written by the programmer? Or a separate man who only writting the manuals?
« Last Edit: 2013.February.25. 09:18:59 by Zozosoft »

Offline BruceTanner

  • EP lover
  • *
  • Posts: 607
  • Country: gb
Re: Importance of documentation
« Reply #5 on: 2013.February.22. 22:56:57 »
Quote from: Zozosoft
These are the Technical informations?
The user manuals (BASIC, FORTH, EXDOS, ISDOS) is also written by the programmer? Or a separate man who only writting the manuals?
The user manuals were written by a proper manual writer but I can't picture him/her in my mind. The specification documents (the ones in a fixed space font with an IS copyright notice at the bottom) were written by the programmers. I can/t remember having the ETn and PER-n numbering scheme though - they might have been added by Enterprise Computers after we delivered them (they would have had electronic copies). The Application Notes were written by Enterprise Computers - I don't remember even seeing them before finding this web site.

You have just reminded me of an amazing dot matrix printer we had...it had two print heads so when you print an assembly listing, one print head printed the mnemonics (code) while the other printed the comments!
« Last Edit: 2013.February.25. 09:19:08 by Zozosoft »

Offline Zozosoft

  • Global Moderator
  • EP addict
  • *
  • Posts: 14733
  • Country: hu
    • http://enterprise.iko.hu/
Re: Importance of documentation
« Reply #6 on: 2013.February.22. 23:36:23 »
Quote from: BruceTanner
(they would have had electronic copies)
Is my dream find these :oops:

Quote
You have just reminded me of an amazing dot matrix printer we had...it had two print heads so when you print an assembly listing, one print head printed the mnemonics (code) while the other printed the comments!
Really amazing! I never hear about same!

The most impressive matrix printer what I used the Epson DFX 5000, it is real Paper Eater :-)
I worked at Budapest Electric Company, and used these printers for printing invoices, formal notices. But the documents not localy created, it is come from central mainframe system then printed in local Novell Netware system.
The problem is: the formating is very bad: printing extra CR/LF at each line (2x paper needed), and extra page feed at the end of each document (many more paper needed). The wasted papers cost millions for a year!
We wrote lot of complaints to the mainframe centre, but not happen anything...
On the Novel systems also not have any chance modify the documents.

Finaly I designed little Z80 "computer" (Z80, 32K EPROM, 32K SRAM, In and Out LPT port) which is put between the server and the printer. It is collected the printed datas, removed the unwanted feed characters, and also converted the Hungarian characters (the mainframe system not localized), then sent to the printer.
I took my Enterprise to my workplace, and developed the software for this project. For testing it is worked on EXOS with file to file conversion.
I was rewarded with several months' salary for the innovation!
The Enterprise is also used for other tasks, for example EPROM programming, and lot of data saving from damaged PC floppy disks!
« Last Edit: 2013.February.25. 09:19:17 by Zozosoft »

Offline BruceTanner

  • EP lover
  • *
  • Posts: 607
  • Country: gb
Re: Importance of documentation
« Reply #7 on: 2013.February.22. 23:48:02 »
Nice one zozo :smt023 The Enterprise strikes again! :smt041
« Last Edit: 2013.February.25. 09:19:26 by Zozosoft »

Offline Tuby128

  • EP addict
  • *
  • Posts: 1449
  • Country: hu
Re: Importance of documentation
« Reply #8 on: 2013.February.22. 23:58:17 »
Nice work Zozo! Well done!
« Last Edit: 2013.February.25. 09:19:34 by Zozosoft »