Planets.nu Documentation Standards

In an effort to maintain consistent documentation, not lose edits, and not lose enhancement ideas, the Planets.nu Documentation team has chosen to implement the following standards for the documentation created. These standards should be treated as "firm guidelines" and not "requirements." Sometimes, it will be necessary to violate these standards, in which case the reason should be commented.

• When an Editor is working on a document for any change not trifling, they are to place a comment to that effect at the top of the page. This comment is to be removed when the editing has been completed. [NOTE: In cases where major changes have been made, it might be of use to leave the date and name along with a brief description.] The comment should include the date, which should be updated frequently. Files marked as being edited for more than a week will be considered available for editing.
• If the above edit is to take an extended period of time, and is likely to cause issues due to confusing wording or HTML rendering, it is advisable to place a paragraph in the top of the document warning users of this.
• When one of the Planets.nu editors creates a document (puts the first meaningful content into it), they may choose to place their Game ID into a comment in the document as the author. No author information should be visible to the user.
• Near the top of each document, there is to be a comment containing a list of pages that reference the document and a list of pages referenced by the document. The file name of the page should be used, and not the page title. These lists are useful in locating orphan documents, and in merging pages.

  The Table of Contents and Master Table of Contents are exempt from this guideline, as complying would be an absurdity. Likewise, and for similar purpose, any first-level page where the majority of the content is links to second-level pages need not contain a list of pages it references. Since the main body of the article is composed of links, the description would merely repeat the article and so be useless.

• There is to be a "back" link at the bottom of each page of user documentation.
• Links need to be formatted properly to ameliorate the quirks of the new interface. Library contents should use HTTPS (https://planets.nu/_library). Links to Players, Sectors and newer posts should be linked through HTTP (http://play.planets.nu/#/) for the time being. Links to older stuff (planets.nu/post/, planets.nu/discussion) should be linked through HTTP as well, as they're not available through the HTTPS path.
• Comments are to be used to indicate that specific changes should be made or considered. For ease of location, they should be near the top of the document, but after the reference lists.
• Comments may be used to track changes while they're being made. After a document is complete, these comments should be removed except on those rare cases that a reason or explanation should be maintained in-line. These comments should generally be removed within one month after the requested change has been completed. This extra time is so that they can assist in the correction of any errors that might have been inadvertently introduced.

  Comments may also be used to track decisions about a document. After the decision is made, the comment should be reduced as much as possible. This is important, as there is a space limit in the DB. Additionally, excessive comments can cause the document to be difficult for the editors to work with.

Thank you.

The Planets.nu Documentation Team

Back