Wednesday, May 13, 2009

Working on Documentation

As part of moving into Alpha2 and preparing for Beta, I'm slowly working on the documentation.  This is in wiki format on the main site (

Any comments or suggestions on how to improve the documentation greatly welcome. 
Any volunteers to help with documentation even more welcome !

There's a dual purpose for documention.  First, of course, is to help document things so people can use it.  (even for me, I actually just stumbled on a feature I forgot I implemented).

But the other purpose is to flesh out problems that are not obvious in the test cases or the code, but become obvious when documenting.  For example I just realized (and fixed) that the only named port was "error", I hadnt actually implemented the implicit stdin/stdout as named ports.  I only discovered this while cleaning up the port redirection page.

The problem with the 2nd part is its way too easy to get sidetracked and start working on implementation ... 1 minute of documentation can easily lead to hours of implementation ... and hence thats why the docs are in such bad shape :(

Suggestions on what to focus on and how to avoid getting caught up in implementation welcome.

1 comment:

  1. Thanks to Mr Ishaq for the suggestions, I've decided to go with a "How To" page to help get started. A big problem I have is I dont know the target audience so Its hard to make assumptions about where to start. So instead I'm going to go random !


Due to comment spam, moderation is turned on. I will approve all non-spam comments.