= Package Documentation =

== Overview ==
The Orchard team aspire to have public-facing documentation for all software packages distributed via munki and the Orchard Software Centre. This documentation is intended both for end users and for IT support staff, and can be found by browsing the links in the Display Name column of [[Software/List|the software list]]. The documentation follows a simple template which embeds a dictionary of key/value pairs into the static wiki page for the software.

== Documenting a package ==
 1. Once the software is in the production repo, it will appear in the software list. Click on the Display Name of the software to take you to an empty wiki page.
 1. Create this page from the template `Software/SoftwareTemplate`
   * Once created (as noted in the comments at the top of the page):
     * update references to `**DISPLAY_NAME**` with the package display name (e.g. `Amazing Widgets`)
     * update references to `**NAME**` with the package name (e.g. `Amazing_Widgets`)
 1. Click save changes, we will come back to this page momentarily.
 1. Now you can click on the link at the end of the 'Generated from !InfoDict' text on the saved page to take you to the information dictionary for this software pkg.
 1. Create this page from the template `Software/InfoDictTemplate`. The comments in the template should help you fill out the fields, but to clarify:
    * `DisplayName::` should be `display_name` from the munki pkginfo
    * `Description::` should be `description` from the munki pkginfo
    * For the `LicenceStatus::` field choose from the options listed in the comments. e.g. if the software is completely free and open source, enter `foss`
    * For `LicenceURL::` either include a relevant URL to licensing information or copy and paste the link to the anchor provided, and detail the licence situation later on the page generated above from the !SoftwareTemplate
    * For `BuildType::` enter `autopkg` if a recipe or override has been created, otherwise `manual` if the software has been built some other way
    * For `BuildInfo::` If you entered `autopkg` above a link to the .munki recipe in one of the ox-it recipe repos is enough (even if this is a private repo), otherwise copy and paste the link to the anchor provided, and detail the build prodess later on the page generated above from the !SoftwareTemplate
    * `Developer::` should be `developer` from the munki pkginfo
    * For `SupportStatus::` choose from one of the options listed in the comments. For instance if you were part of Orchard for ITSS you would put "funded by <YOURDEPARTMENT>" here.
    * For `SupportedOSVers::` glean the supported OS versions from the pkginfo's `min_os_version` and `max_os_version` keys and format it according to the options in the comments, or put `all` if nothing is specified there.
    * For `RestartRequired::` enter `yes` if the pkg will cause the Orchard Software Centre to log the user out to install and reboot, otherwise `no`
    * For `Requires::` enter all the `name`'s of the pkgs in the `requires` key from the pkginfo, separated by spaces if they are an array.
    * For `UpdateFor::` enter all the `name`'s of the pkgs in the `update_for` key from the pkginfo, separated by spaces if they are an array.
 1. Save this page and go back to the software's main documentation page.
    * You should see the fields you added to the !InfoDict populating the information here now.
    * Edit this page adding any further information required, and delete the anchors and headings for the sections you do not need to fill out.
 1. Once you are happy, save the edits to the software page.

----
CategoryWikiToDo