Documentation Standard

From ComputerCraft Wiki
Jump to: navigation, search
This is a draft document.
Feel free to submit changes and suggestions at the Talk Page. Please don't edit this document directly!

The Documentation Standard encourages a constant standard of the quality and structure of all the documentation provided across the entire ComputerCraft Wiki.

The primary objectives of the Documentation Standard are:

  • to assist in keeping documents consistently formatted and organized;
  • to assert whether information is clear, easy to understand and easy to access;
  • to ensure a sufficient technical documentation for users who are technically inclined or have a technical background; and;
  • to provide a level-of-quality assessment on a document-by-document basis;

The Documentation Standard is not law; however, it is likely to be expected that future documentation changes do their best to comply with this document (to assist with cleaning and reducing the workload of the Administrators, as well as maintaining and improving the quality of the ComputerCraft Wiki).

Making Changes

Overall, on the ComputerCraft Wiki, users are expected to follow the Assume Good Faith (Wikipedia link) policy.

We also assume that people will remain on-topic and make relevant changes. The don't be dense, don't be a mook, don't be a dick or a troll principles apply here.

Making Changes to Pages

Anyone can make changes on the ComputerCraft Wiki. You may at any time change or tweak pages and content as you so please, but we ask that you keep the following in mind:

  • make sure your changes contain correct spelling, grammar, and most importantly, make sense;
  • try with your best efforts to make sure your changes fit with the guidelines below - if in doubt, ask someone to read your changes;
  • press the "Show Preview" button before submitting a change, and read over your change to find any problems or errors;
  • give us a "Summary" of your change every time, so those of us in #computercraft can know what you've done without having to visit; and finally;
  • do NOT blank pages to be deleted, ever! If a page is to be deleted, tell us why, but don't blank everything. Tag it with the {{Delete}} tag and move along.

Getting Feedback and Leaving Notes

Anyone can leave a note on a page on the ComputerCraft Wiki. The talk pages are intended for intelligent, reasonable discussion about the content and potential issues with a particular page. While this is an important and helpful tool, we ask that you:

  • sign all posts by using four tildes, like so - "~~~~" - this becomes something like "AfterLifeLochie 02:40, 30 November 2012 (MSK)", which we can use to find out when you made the comment;
  • as listed above, that you keep all discussion relevant and on-topic to the issue at hand;

Documentation Components

Function Pages

Function Pages are a critical portion of the documentation wiki. The Function Pages are top-down descriptions and explanations on all non-standard Lua methods within ComputerCraft - this also extends to API function pages, which also qualify under the Function Pages banner.

{{Function}} provides our preferred-structure of functions - it provides a uniform and easy-to-use template across all function pages.

The use of {{Example}} is also preferred over just plain code-blocks for examples embedded into the Function Pages.

The Function Pages (and the data filled into the applicable {{Function}} item) should (at an absolute minimum) provide a top-down explanation of a given function, the function's arguments, any of the function's output(s), the method(s) the function can be accessed through, which API and system it belongs to, and where possible, one or more clear, functional examples.

In addition, the Function Pages should also have sufficient technical information (such as links to the Lua 5.1 Manual, working examples, detailed information) for users whom are technically inclined or have a technical background. A deeper understanding of how the function works, and it's behaviours (and quirks) helps to further expand the depth-of-knowledge of others.

API Pages

API Pages list all the available functions included inside a particular API. They may link to appropriately bundled Function Pages (where appropriate), to parts of the Lua 5.1 documentation, and to other appropriate resources.

The API pages must provide a list of all the functions bundled within the API, followed by any additional comments.

A short synopsis at the start of the API is considered appropriate, so long as it does not obstruct the main table or the flow of information (remember: ease-of-access and information vs clutter). In addition, it is also acceptable to include code snippets of one or more useful examples of the use of the API in question.

Code examples and snippets should conform with the Code Formatting section, and should, where possible, utilize the {{Example}} template (for consistency purposes).

Code Formatting (Examples, Snippets, etc)

Code Formatting is very important when distributing and explaining functions. However, poorly (or completely) unformatted code can make understanding of the intended purpose of a sample of code hard, to almost practically impossible.

On the ComputerCraft Wiki, we encourage the use of wrapping code inside a "code chunk" by using two spaces before each line, like so:

 This is an example of a "code chunk". The start of all the lines in
 this example are prefixed with two spaces.

In addition, to ensure that code is easy to understand, dissect and read, we ask that:

  • two spaces are preferred over four tabs and/or spaces, as ComputerCraft's "edit" program uses two spaces;
  • clear, concise variable, function and block names are encouraged;
  • use of comments to explain blocks of code, or individual functions;
  • where possible, comments explaining the "flow of thought", that is, the intended process that must occur;

Tutorials and other Unofficial Content

Tutorials and Unofficial Content make up a significant portion of the ComputerCraft Wiki.

Tutorials are significantly important, as they provide step-by-step instructions or code to demonstrate a principle, methodology or system that users may be unable to complete on their own, may have trouble understanding, or are just getting into the feel of ComputerCraft. For this reason, we ask that they follow, at least, the Code Formatting guidelines above when delivering code, and where possible, use accompanying links to other pages on the wiki, or the Lua 5.1 Manual. We consider the correct transfer of information and coding standards a high-importance.

Unofficial Content, such as unofficial API's and other programs and media should, where possible, try and reasonably comply with any and all of the above guides. It is the responsibility of the content authors to ensure their own unofficial documents are up to standard, or they may be edited ruthlessly by Administrators.

What about X? Y isn't included here?

If in doubt, you can chase the Administrators on their talk pages, ask in #computercraft, or, if worst comes to worst, ask at the Forums. One or more of us may be able to help you out or at least point you in the right direction.