I think what confuses most users who are new to packages is the larger question of where to put them and how to use them. I am going to discuss this in a larger context.
Suppose you are working on some significant or extended topic, which we will call TopicX. This topic might include many notebooks of various kinds and several packages, and perhaps later WRI style paclet documentation.
First you need a place to collect all your work on TopicX. The best place to collect this is in a TopicX folder in your private Applications folder. You can find this Applications folder by evaluating
$UserBaseDirectory in Mathematica and then looking for the pre-existing Applications folder. Many users find some reason to put their applications elsewhere, but I think this is the best and standard location for a number of reasons, which I won't expound on here.
Within the TopicX folder you could build a folder structure for your own notebooks and other files associated with the topic, according to your own preferences. So far, no package.
As you work on the topic you will find it convenient to develop various routines associated with the project. You might develop them in a notebook proper and then move them to a Routines section at the top of the notebook. You might leave a routine there for a while and even copy it from notebook to notebook until you are satisfied that it works properly. I often call this "package purgatory". For these routines write usage messages, a
Attributes if any,
Options definitions if any, error messages if the routine checks for errors. If all this is done, the routine is ready for "package heaven".
An application may have more than one package associated with it. I am going to assume that this is the case, or a future possibility, and give the packages names other than TopicX. So let's assume that your first package will be named Package1. In the TopicX folder create a new file named
Package1.m. You could do this by opening Mathematica, using Create New> Other> Package, and then saving the file as
Package1.m in your TopicX folder.
Package files can have sectional organization just as regular notebooks. You may wish to create sectional organization for the BeginPackage and Usage messages, and for the Private section, and for an End section. You may also want subsections for individual routines. According to your taste. Package files can also contain Text cells for annotation or notes.
The actual Mathematica code in a Package file is contained in Code cells. These are automatically Initialization cells and they are evaluated when the package is loaded. Cells that have the Input Style are not part of the package. (Converting a Code cell to an Input cell is a way to save an old version of a routine.) You can copy your routines from the notebook where they were developed to the package file. Usage messages to the Usage section and code to the Private section. Depending on how you copy you may have to switch Input cells to Code cells using the context Style menu. Code cells, especially usage messages often do not conveniently break and require horizontal scrolling. Sometimes it helps to temporarily switch them to Input cells for editing.
Following the folder structure, the
BeginPackage statement will be:
and the package could be loaded from anywhere with:
However, there is another very convenient feature that WRI has implemented. If a user executes the load statement without the package name as follows:
then Mathematica looks for an
init.m file within a TopicX/Kernel folder and evaluates it.
So create a Kernel folder within TopicX and an
init.m file within it, and include the statements:
if there are other packages in the application.
That's it. I won't discuss the details of package code since that is pretty well discussed elsewhere.
Later, if you want to add WRI paclet documentation, you could obtain Wolfram Workbench. You could just transfer the package files to Workbench and start writing Guide and Function pages. One important thing to remember is that all the routines from all the packages in TopicX are included in a single documentation paclet for TopicX.