Partner Platform Development Manuals

Overview

This manual is one of a set, written by and written for developers who work with any of the various Partner Platforms.

There are three manuals in the set:

The Introduction to Partner Development provides an introduction and overview of the Partner Platform, along with a series of tutorials intended to help the reader quickly learn the basics and capabilities of the platform. Any reasonably technical person should be able to comprehend the Introduction, and it should let the reader know what the various Partner platforms are, what they are useful for, and what sorts of things you might develop in them.

The Partner Development Manual provides in-depth documentation of the many frameworks and subsystems of the Partner Platform, grouped by topic. It is intended for those serious about and actively engaged in Partner Platform development, and should serve as a useful companion for such work.

The Partner Development Reference provides very fine-grained details of the Partner Platform API and other components. Much of this document is machine- generated from the platform source code. This results in a substantial amount of information, and the Reference is not intended to be “read”, per se, but instead referred to at need.

Availability and Formats

Each of these manuals is available in HTML and PDF formats. Readers may access the manuals online at the Partner Developer Portal or by downloading and installing the corresponding Partner Platform module.

Much of the documentation is version-specific, so builds of the manuals are available alongside the released versions of the Partner Platform at the Partner Update Site. Be aware that if you are not using matching document and platform versions, details may vary and examples may not work correctly.

The HTML versions of the manuals have a built-in search feature. Since they are published online, you may also use any standard search engine (such as Google) to find information, using the following query style:

partnersoft.com TOPIC

for example,

partnersoft.com modules

Audience

While anyone is welcome to read these manuals, the intended audience consists of Partner, non-Partner, and third-party technical staff engaged in:

  • development,
  • production,
  • support,
  • IT, and
  • management.

It is important to note that these manuals are used internally at Partner as well as externally. One of Partner’s core principles is openness; we do not hide information unless there is a substantial legal or similar reason to do so. We also feel that the only way to ensure the quality of development documentation is by using it ourselves, every day.

Developers are technical people, not necessarily full-time professional programmers, who want to customize or extend the Partner system in some manner.

Production, support and IT folk are an important audience as well. They need more technical knowledge than an end-user, and often have to write or troubleshoot scripts, modify configuration files directly, and do other things “under the hood”. There are also always “power users”, who need or want deeper information about the system so that they can use it more effectively.

A less technical, but still important, audience is management types. Often an engineering manager has taken a Partner development course to find out what the system can do. They then hand off the work to a subordinate, usually a younger engineer with more programming experience and less responsibilities.

Managers of companies evaluating Partner for use in their business will also benefit from these documents, which should explain the capabilities of the Platform and demonstrate the maturity and openness essential to serious investment.

Examples include:

  • a Map Publisher user writing a complicated transform script,
  • a consultant writing a custom integration module,
  • a software company writing an add-on module for Staking,
  • a software company developing full applications on Partner,
  • a Partner production tech who wants to automate some configuration,
  • an IT staffer who needs to troubleshoot a nasty Update problem,
  • a manager who wants to know whether Partner might be a good platform for visualizing problem transformers,
  • a young engineer interested in displaying AMR results on the map,
  • a new Partner developer in training, and
  • an experienced Partner developer who needs to understand an unfamiliar subsystem.

Documentation Flavors

These flavors of document may appear in various places in any of the manuals:

  • tutorials - pedantic exercises in specific tasks,
  • how-tos - no-nonsense instructions for tasks,
  • troubleshooting - instructions for examining and resolving problems, and
  • API - guide to programming calls.

Versions

A version of the documentation will be packaged and frozen with each release version of the Partner system. This will be maintained as long as the release itself is maintained. Changes to an older release’s document may be made to correct serious problems but they will be minimal.

So, most additions and changes to the manuals will be in the current working version, and this should therefore always be considered the version of record. An exception to this is the reference documentation, which includes things such as the Platform JavaDoc API. JavaDoc is automatically generated from Java source code and therefore is specific to a version.

Thus, a programmer targeting version X of the software should always refer to version X of the `Partner Platform Reference`_, and should use a combination of the latest version and version X of both the Introduction to Partner Development and the Partner Development Manual. The latest version of these may include better descriptions and more information, while version X may be more accurate in version-specific details.

The Partner Documentation Wiki

For many years, the Partner Documentation Wiki has served as the repository for Partner Platform development and other technical documentation.

We have no plans to retire the wiki; however we are now migrating developer-type documentation to this manual set and removing them from the wiki and are no longer actively maintaining developer-type documentation in the wiki.

When an article is moved, we place a note in its stead referencing the manual it was moved to.

Authoring New Sections New sections should be authored in Google Docs, which allows a more lightweight form of editing and includes commenting capabilities that are useful for bootstrapping a new piece of documentation. Once the document is considered satisfactory, it can be copied into the manuals in the appropriate place.

The authoring and review process should be batched to allow various people time to comment. Workflow should be something like this: one or two authors write the bulk of the section, draft is presented for review, review period lasts 1 week to 1 month depending on size/criticality of section, comments and edits are collated into a second draft, shorter review period for second draft, commends and edits are collated for third draft, and third draft is copied into the manuals and maintained there henceforth.

Extensive rewrites can follow the same process as for new sections. Project Design Documentation Project design documentation should include any changes or additions needed for the manuals. In the case of large new software projects, this may be in conjunction with or combined with the Authoring New Sections process described above. Minor Edits Any Partner employee should feel welcome to make minor edits as needed, for example to spelling, grammar, or layout. Implementation Modules These modules now exist, under http://developer.partnersoft.com/subversion/modules/branches/5/: PartnerDevelopmentIntroductionManual - Introduction to Partner Development PartnerDevelopmentManual - Partner Development Manual PartnerDevelopmentReferenceManual - Partner Development Reference

The naming convention is tedious but clearly indicates that these are all manuals.

The PartnerDevelopmentManual is fleshed out and works. It is derived from the prototype “Big Book of Partner” described below. Building A Makefile at the top level of the module constructs its documentation.

TODO: make any changes necessary to work with our current build server Prose Source Format The Sphinx documentation tool (http://sphinx-doc.org/) is used for prose and the overall structure of the document.

Sphinx is written in Python, is cross-platform, and uses simple text files written in a wiki-like markup language as its source. It produces both PDF and HTML documentation, and the HTML includes a decent search engine and navigation tools. Subdocuments can nest indefinitely and it seems to be able to handle a large volume of information. Diagram Source Format TODO: select a cross-platform diagramming tool as standard. Paul currently uses OmniGraffle, which is excellent but only available on Mac. Generated Documentation Generated documentation should be integrated into the build system for the module. The reference manual will rely most heavily on generated documents. Editing and Maintenance As with any other module, these modules may be checked out from subversion, modified, and the changes committed.

The Eclipse IDE has many useful tools for this process and is a standard tool for our developers. The Sphinx text files may be edited directly in Eclipse.

Other subversion clients and editing systems may be used, including something like TortoiseSVN and the Windows File Explorer in conjunction with a decent text editor. Version-Specific Builds The modules are built and packaged just as other modules are for a specific version. In addition, the contents are posted online and associated with the version’s update site (e.g. http://update.partnersoft.com/4.12/doc/ or similar).

TODO: decide where to put them Current Working Build The current working version is built on a regular basis and posted to the Partner development site. It is not associated with a specific version, and should be assumed to always be “under construction” but should also be assumed to have the most recent and accurate general documentation. Migrating Existing Documentation Documentation copied from the wiki, or redundant with documentation in these manuals, should be deleted from the wiki as soon as the manuals are generally available. This will prevent stagnant and inaccurate documentation from lingering.

Prototype A prototype of the Partner Development Manual, written in Sphinx, is here: html - http://download.partnersoft.com/developer/BigBookOfPartner/html/ pdf - http://download.partnersoft.com/developer/BigBookOfPartner/latex/TheBigBookofPartner.pdf