LinuxQuestions.org
Register a domain and help support LQ
Go Back   LinuxQuestions.org > Forums > Non-*NIX Forums > Programming
User Name
Password
Programming This forum is for all programming questions.
The question does not have to be directly related to Linux and any language is fair game.

Notices

Reply
 
Search this Thread
Old 07-30-2005, 06:00 PM   #1
Xyem
Member
 
Registered: Apr 2005
Distribution: Fedora Core 4
Posts: 100

Rep: Reputation: 15
Writing Program Documentation


I have currently set myself a project of writing a game in Perl/Tk as a present for my girlfriend. However, once I have completed a basic version, and given it her, I intend on making the code open source and try to build a community around the game so people can add to it, make improvements etc. to it (hey, one can dream :P).

Firstly I am completely new to Perl/Tk but Perl is a familiar friend to me (it's the only language I know how to do anything with, even though I've had no lessons in it, learn from messing with it really) so I am not looking for documentation to read.

Secondly my programming style is perhaps slightly haphazard, I've never programmed a game, or even a fully fledged program for any reason, commercial or otherwise. I've adopted my own style which some may find hard to follow.

I intend on writing documentation of my game as I go along, explaining how things work and how it all ties together etc etc. so my question is this.

Is there a FAQ or walkthrough or something similiar where I could read about how to write documentation up? Such as formats, what to include, etc etc.
 
Old 07-30-2005, 06:59 PM   #2
rjlee
Senior Member
 
Registered: Jul 2004
Distribution: Ubuntu 7.04
Posts: 1,990

Rep: Reputation: 67
Firstly, read the perlpod document from the Perl documentation i.e. type this into a terminal:
Code:
perldoc perlpod
I would suggest that you try and keep (and maintain) the documentation along with the code, with a block of POD code at the start of each file or sub. Include in this block what the purpose of the file/sub is, and what each's sub's interface is. By interface, I mean how the sub processes @_, what it returns, and what it can can throw (i.e. what is passes to die). This will make it much easier to maintain if you do get a community-based distribution, as any incorrect documentation will stand out when editing the code.

I would also suggest creating a separate file showing a more general overview saying how the code is organised.

Don't forget to explain why design decisions were made in the documentation, as well as what the code is supposed to do.
 
  


Reply


Thread Tools Search this Thread
Search this Thread:

Advanced Search

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is Off
HTML code is Off


Similar Threads
Thread Thread Starter Forum Replies Last Post
Need help writing a simple program justintime32 Mandriva 8 03-04-2005 08:12 PM
about hpux - documentation & installation program kpachopoulos Other *NIX 1 01-25-2005 11:49 PM
CD Writing program? Which is best? nro Linux - Software 14 09-01-2004 10:19 AM
Writing and executing a program Russb Linux - Software 1 07-25-2004 06:49 PM
TV overlay (Planning on writing documentation) bkeating General 1 05-01-2003 03:00 AM


All times are GMT -5. The time now is 11:32 PM.

Main Menu
My LQ
Write for LQ
LinuxQuestions.org is looking for people interested in writing Editorials, Articles, Reviews, and more. If you'd like to contribute content, let us know.
Main Menu
Syndicate
RSS1  Latest Threads
RSS1  LQ News
Twitter: @linuxquestions
identi.ca: @linuxquestions
Facebook: linuxquestions Google+: linuxquestions
Open Source Consulting | Domain Registration