Welcome to the most active Linux Forum on the web.
Go Back > Forums > Non-*NIX Forums > Programming
User Name
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.


  Search this Thread
Old 07-30-2005, 07:00 PM   #1
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, 07:59 PM   #2
Senior Member
Registered: Jul 2004
Distribution: Ubuntu 7.04
Posts: 1,991

Rep: Reputation: 76
Firstly, read the perlpod document from the Perl documentation i.e. type this into a terminal:
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.


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 09:12 PM
about hpux - documentation & installation program kpachopoulos Other *NIX 1 01-26-2005 12:49 AM
CD Writing program? Which is best? nro Linux - Software 14 09-01-2004 11:19 AM
Writing and executing a program Russb Linux - Software 1 07-25-2004 07:49 PM
TV overlay (Planning on writing documentation) bkeating General 1 05-01-2003 04:00 AM > Forums > Non-*NIX Forums > Programming

All times are GMT -5. The time now is 04:46 PM.

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