Recent Changes - Search:




Help.HelpTheHelpFiles History

Hide minor edits - Show changes to markup

January 24, 2006, at 06:21 AM by -
Added lines 1-65:

Alpha's wealth of documentation includes www files (see AlphaDocumentation), 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. JohanLinde contributed a great deal to the Alpha Manual and other files before becoming consumed by other projects. DonavanHall and CraigUpright 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:

  • Requests for more documentation
  • Suggestions for improved documentation
  • Changes which have been submitted in development releases

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. CraigUpright 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

  • New "Named Marks" menu needs documentation in Alpha Manual

(status: Craig is working on this)

  • Does the behavior change for twiddle need to be documented?

(status: none)

  • Changes in "Open Windows" needs to be documented

(status: none)

  • Electric Menu, Document Projects Help files need updating

(status: Donavan has some help files/tutorials already written for Document Projects. Please see Menus.ElectricMenuIdeas 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

Page last modified on January 24, 2006, at 06:21 AM
Hosted on Logo