Help the Help Files

Alpha's wealth of documentation includes www files (see Alpha Documentation), the Help files that appear in the Help menu, and anything that appears when clicking on any of the hyperlinks found in the "Packages" help file. Johan Linde contributed a great deal to the Alpha Manual and other files before becoming consumed by other projects. Donavan Hall and Craig Upright are currently maintaining portions of this documentation, maintainers who have not orphaned their packages take care of the rest.

This page is devoted to improving Alpha's documentation, and is divided into three major sections:

Feel free to add anything to either of the first two sections. Donavan and Craig review this page periodically to update Alpha's documentation, and will move items to the third section once the changes have been incorporated into development releases.

Thanks for helping !!

What's New?

24-apr-2001: v7.5 will feature a new Help mode with a help menu. Craig Upright is spearheading this effort. If you have any ideas or requests, let us know. How would you like Alpha to help you?

Requests for more documentation

(status: Craig is working on this)

(status: none)

(status: none)

(status: Donavan has some help files/tutorials already written for Document Projects. Please see Electric Menu ideas for suggestions on updating the menu.)

Suggestions for improved documentation

Put your suggestions here!

(Rowland, 29 April 2003):

The whole edifice needs completely restructuring from the ground up. This does not mean that existing documentation needs throwing away: it mostly needs re-arranging so it makes sense. Alpha's menu structures also need re-arranging so they make sense too, with particular regard to the various preferences settings.

The re-structuring should ensure that new users can look up things when they need to. This means that the documentation must not assume that the user understands Alpha's very complex structure. For example, I want to be able to turn off all of Alpha's auto-indenting and auto-continue-comment mis-features (they always get it wrong and never get it right). it's not possible to look up how to do this in Alpha's documentation at the moment: the new structure must allow this to be done.

I can't make any concrete suggestions because Alpha mostly leaves me baffled: I don't understand enough about it to make detailed comments. I'd like to - but the documentation needs improving before I can understand it well enough to suggest such things.

Additional Comments

(Rowland, 29 April 2003):

Don't do this via a Wiki. Alpha's documentation needs good structure. With a Wiki, you can't have good structure - so trying to fix Alpha's documentation the Wiki way will inevitably result in a bad outcome. Basically, do it like this, and you'll be wasting your time.

I think what's needed is for this job to be run by a team which works out the needed structure and implements it, taking suggestions as and when via (maybe) email and putting the worthwhile ones up on a Web site so that others can see what's being done.

Changes which have been submitted