flat assembler
Message board for the users of flat assembler.

Index > Heap > Technical Documents

Author
Thread Post new topic Reply to topic
cypher



Joined: 07 Apr 2011
Posts: 51
Location: The cave
cypher
I've been researching about writing technical documents and I was wondering if any of the forum members actually write technical documents for your programs; especially in projects. I figured that it would be a way to maintain your programs.

Do any of you write technical documents?

_________________
When all in life fails, get weird and disappear into the mountains
Post 09 Apr 2011, 16:08
View user's profile Send private message Reply with quote
asmhack



Joined: 01 Feb 2008
Posts: 431
asmhack
It's a good idea for big projects like an OS for example, for everything else comments are enough IMHO.
Post 09 Apr 2011, 16:15
View user's profile Send private message Reply with quote
cypher



Joined: 07 Apr 2011
Posts: 51
Location: The cave
cypher
agreed. yea, it might be a little to formal to write a techdoc for a something like a simple text editor or IDE
Post 09 Apr 2011, 16:52
View user's profile Send private message Reply with quote
JohnFound



Joined: 16 Jun 2003
Posts: 3500
Location: Bulgaria
JohnFound
What actually you mean in the term "technical documents". Is it some kind of standard or you mean things like reference manuals, tutorials, etc.
Post 09 Apr 2011, 16:57
View user's profile Send private message Visit poster's website ICQ Number Reply with quote
cypher



Joined: 07 Apr 2011
Posts: 51
Location: The cave
cypher
It can be said that a "technical document" consists the some source code, algorithms, test data, architecture, design, etc. of a program. It basically contains technical information about the program, and is usually read by programmers just in case other programmers want to develop the program.

Yes, reference manuals are technical documents, but not tutorials.
Post 09 Apr 2011, 17:19
View user's profile Send private message Reply with quote
JohnFound



Joined: 16 Jun 2003
Posts: 3500
Location: Bulgaria
JohnFound
Well, we (me and pelaillo) are writing a reference manual about FreshLib library. Actually pelaillo performs most of the work on it. I only wrote some initial notes. The reference manual is implemented as wiki pages in Fossil SCM repository. (here)

IMHO, the main problem with these kind of documentations is that it is hard to keep them up to date. The project develops further and the documentation have to be revised all the time.
Post 09 Apr 2011, 19:33
View user's profile Send private message Visit poster's website ICQ Number Reply with quote
cypher



Joined: 07 Apr 2011
Posts: 51
Location: The cave
cypher
Wow. That's a big project. Incredible.

I like how your manual is structured. It's user-friendly, and informative. [That's my opinion]

As you mentioned above, these documents are hard to keep up to date, and thus, a project like this would be hard to maintain (in terms of documentation). For example, if you should have a major change in your project, then a majority of the reference manual must be rewritten.
Post 09 Apr 2011, 20:20
View user's profile Send private message Reply with quote
JohnFound



Joined: 16 Jun 2003
Posts: 3500
Location: Bulgaria
JohnFound
cypher wrote:
Wow. That's a big project. Incredible.


Thanks. Smile

Quote:
As you mentioned above, these documents are hard to keep up to date, and thus, a project like this would be hard to maintain (in terms of documentation). For example, if you should have a major change in your project, then a majority of the reference manual must be rewritten.


That is why some parts are not documented at all - for example the GUI subsystem description is incomplete and out of data. But, for example, memory functions and strlib are relatively stable and well documented.

Anyway, is is known that programmers hate to document their sources. Very Happy
Post 09 Apr 2011, 22:24
View user's profile Send private message Visit poster's website ICQ Number Reply with quote
cypher



Joined: 07 Apr 2011
Posts: 51
Location: The cave
cypher
Quote:
Anyway, is is known that programmers hate to document their sources.

I knew what that feels like

Keep up with the documentation.
Post 17 Apr 2011, 03:43
View user's profile Send private message Reply with quote
Display posts from previous:
Post new topic Reply to topic

Jump to:  


< Last Thread | Next Thread >
Forum Rules:
You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum
You can attach files in this forum
You can download files in this forum


Copyright © 1999-2020, Tomasz Grysztar.

Powered by rwasa.