Overview of objects in Ponydocs
Ponydocs objects are the containers and content in the documentation system. This topic provides a high-level overview of what they are and do. Procedures for creating and working with these objects are in later topics.
Ponydocs supports multiple products, each with their own versioning scheme. A product contains a version scheme, manuals (each with a table of contents), and topics. You must define a product before you can create a version scheme for it and add content (manuals, topics, etc). A product has a short name and a display name. The short name is used in all URLs for that product and cannot be changed once the product is created. The display name is the full name of the product, and can be changed as desired.
For example, you might have a product called "App for Sparkly Unicorn Data". You probably don't want all the URLs to all the topics in all the manuals about that app to have that full string in them, so you might choose "UnicornData" as the short name, resulting in URLs like:
A product must have a version scheme before you can create manuals within it. A version scheme just means it has to have one or more versions available to which content can belong, or apply. Version schemes can contain alphanumeric text, so you can have things like "2.0beta" "v.098" and so on. Typically, the versions defined for a product in Ponydocs map to (or match exactly) the versions of the product or system being documented.
Ponydocs uses version tags to denote what topics, manuals, and tables of contents belong to which version of the product. Version tags are a type of MediaWiki Category: tags , except that there's no hierarchy of versions, and the notation adds a V into the middle. In Ponydocs, we say that something (an object) is 'tagged' with a version. An object can (conceptually) have any number of version tags. A version tag (in this case for version 1.0Beta2) looks like:
To control access to certain versions of your documentation, Ponydocs provides the concept of "version state". In Ponydocs, a given version can have three possible states: released, unreleased, or preview:
- Released: objects tagged with a version that is in the "released" state are visible to anyone who visits the site. Users do not have to be logged in to see this content.
- Unreleased: objects tagged with a version of "unreleased" are only visible to logged-in users belonging to the 'employees' group in the underlying MediaWiki deployment. The Splunk docs team uses this state when we are working on documentation for an upcoming release.
- Preview: objects tagged with a version of "preview" are visible to logged-in members of the "employees" group in the underlying MediaWiki deployment, as well as to logged-in members of the "preview" group. The Splunk docs team uses this state to provide beta documentation access to designated customers without allowing other users to see this preview content.
The state of a version can be changed. For example, over the course of a development/release cycle of the product you are documenting, you may want to transition the version of the documentation from unreleased, to preview, and then to released when the product ships.
The concept of "latest" version
URLs in Ponydocs include a version string so that users can link directly to a specific version of a product's documentation. URLs that include version information look like:
However, you usually want users to go to the latest (released) version of the documentation, and you don't want to keep having to update a URL you've posted somewhere, so Ponydocs also supports the concept of a "latest" version. You can replace the version number in any URL with "latest" and that URL will always go to whatever the latest version in "released" status of that object is. Like so:
Additionally, the first time a user visits a given product on your Ponydocs site, that user will be placed into the "latest" version as well (as well as any time that user's cookie expires). Similarly, if a user selects a version other than the latest one, that user will be returned to that version the next time he or she visits the site and product, unless their cookie expires.
A product can have one or more manuals associated with it. Like products, a manual has a short name and a display name, to help keep URLs short. In the example URL above, the manual's short name is "Install", and the display name might be something like "Installing the App for Sparkly Unicorn Data". The manuals for a given product are listed on that product's landing page.
Note: Manuals don't technically have version tags applied to them; the version tags instead apply to instances of the tables of contents for that manual (because the same manual can change a lot between versions).
Tables of contents (TOC)
A manual is built from a TOC, and represents the structure of that manual for a given version or range of versions. TOCs are tagged with versions, but not all topics within a TOC have to apply to all the versions to which the TOC applies.
A manual can have one or more topics within it. Topics are tagged with versions. Topics contain the actual documentation/content that visitors to the site see.
What is Ponydocs?
Create a product
This documentation applies to the following versions of Ponydocs: 1.0