In reply to George Woodrow I have been documenting a rather large application, Grassmann Calculus, with a beta version of Workbench 3. And another developmental application also. It basically works, but it required a fair amount of effort, back and forth with support, and installing of obscure file types to get it working.

In Mathematica 5 it was possible for every user to do documentation. One just wrote a text file. Yes, the new paclet documentation is much better but now nobody except those who pay extra through Premier Service or otherwise can write documentation. And there is not even a standard facility for doing it. WRI should consider a possible application or program specialized for user documentation - either outside of Workbench or maybe a stripped down version of Workbench. It should be available to EVERY user. And they should listen carefully to users and third party developers because their needs are not exactly coincident with internal documentation. One important requirement is that user produced documentation should have the same 'look and feel' as standard Wolfram documentation.

The fact that ordinary users have been cut off from documentation since version 5 looks as if this is by deliberate decision. It is a HUGE design and business mistake.

People in the community should think more in terms of "applications" and a little less in terms of "packages". An application may or may not include packages. It may not initially include a package but add one later. It is just a good way to develop, organize, preserve and communicate your work around some particular subject matter. If you start out the right way it's easy to grow into the more advanced features as you are ready for them. This is discussed in my essay A Mathematica Style. It is something everybody should consider, not just "developers". Except for the ability to document it is already designed and provided by WRI.

It's basically easy to write packages and, if Wolfram would provide the facility, to write documentation. Writing documentation is not just some irksome chore. It's part of developing and preserving your own work. If it's difficult to document how your routine is used then maybe it's badly designed and you should change it. A year from now will you remember how some routine was used or where there were some examples? Documentation could also include test examples. The examples would probably be written at the time you developed the routine so why not just copy them to a documentation page?

Many more users should be writing packages and documentation and consider it as just part of standard Mathematica usage.

On the name conflict with System. Two things: If one does not use UpperCase first letter for functions and symbols names in the package (as they should ;) then the chance of conflict is almost zero. Second: I always think it is best to call a function in a package using the syntax

  packageName`foo

After loading the package even though adding the context name is not needed. But suppose a package now had a function called NDSolve and one used

    packageName`NDSolve 

To call it, then there is no conflict, right? Would this not resolved the issue of name conflict? May be Mathematica should make this a requirement for calling functions in non-system context, i.e. one must always add the context name. I do this myself all the time, just to make it clear in the code, where a function came from, unless it is from the System of course. This way one can write

      packageOne`foo 
      packageTwo`foo 

in the same code and know from which package each function comes from. Do you think there will still be problem if these two things are followed by package developers and users?

Nice points!

Actually I think a `DistanceMatrix would suffice instead of a fully qualified name. It shouldn't be such a breaking change to get used to adding a heading `.

I agree completely. Support for 3rd party packages used to be done by a group of 3 people. Now it is a collateral duty for one person.