Editing the Wiki

From Jubilee
Revision as of 15:40, 22 December 2020 by Poofjunior (talk | contribs)
Jump to navigation Jump to search

All are welcome to edit the wiki, but do read these guidelines first, or your changes may be reverted! Before you can edit the wiki, simply request an account, and our wonderful team of humans will follow up to make sure you're not a robot.

Wiki Goals

The primary goal of the wiki is the creation and sharing of knowledge related to working with Jubilee.

Syntax

The Jubilee Wiki uses the MediaWiki syntax and a series of plugins or widgets to offer special conveniences like code boxes, etc.

Wiki Organization

In a MediaWiki, there's no strict page hierarchy. In other words, pages aren't organized into folders of folders. To loosely organize pages, we can create internal links on one page that take you to another page. In this way, information is tightly connected, joined by links. Feel free to use internal links liberally.


Let's try to keep the wiki friendly to newcomers and frequent flyers. That is, keep frequently accessed information in the Sidebar. Make it easy to find. Examples include: Assembly instructions and Maintenance. Topics in the Sidebar should be broad (example: assembly instructions). They should be entry points for building Jubilee or understanding how Jubilee works. Topics deep in the page structure should be specific (i.e: tuning retraction settings on the Default Extruder).

Jubilee is aimed at a range of multitool applications. While Jubilee's most common use case is multi-material 3D printing, let's make sure that we preserve a page structure that provides equal entry points to other applications so they don't get buried.

Voice

Inclusivity

At all costs, avoid statements that are discriminatory, racist, sexist, homophobic, transphobic, culturally insensitive, or express hatred in any way.

Normative Statements

Avoid normative statements where possible. A normative statement is a statement that expresses a value judgement.

Example: You should ..

Example: garbage crimp connectors

Avoid unsubstantiated claims.

Example: MIC6 Aluminum is better than 6061 aluminium

Instead, in the case where you, the author, feel this way, try to unpack why and lay out your reasoning. With aforementioned "garbage crimp connectors," what about this particular application makes them a poor choice? With MIC6 aluminum, what makes it better? What characteristics related to both the situation and the material make it a better choice?

Wiki Conventions

Project Versions

The wiki will always reference the most up-to-date version of the project. Information related to older versions should (1) either explicitly mention this up front or (2) create and older page and link to it from the current page.

Links and Uploads

Internal Links

To create link to another page on the wiki, instead of using the URL, use the shorthand notation: Page_Name

Internal Links to Page Subsections

To create links to a page section, use the shorthand notation: Page_Name#Subsection_Name

Design Files

Design files are subject to change between versions. As such, do not upload design files directly to the wiki. Instead, link them to the file in the master branch of the project repository.

Exception: aesthetic-only or placeholder images that clearly point to the most up-to-date version are OK.

External Links to PDFs hosted on Github

Links to PDFs hosted on Github will redirect to a github rendering of the PDF as a PNG image on Github's website like this. Ideally, it would be nice to click on a PDF link that redirects us to a print-ready page that just shows the PDF like this. We can create this effect by modifying the Github link to get Google's PDF doc viewer to render it cleanly in a format that can be readily printed. To do this, prefix the github URL with the following:

   https://docs.google.com/viewer?url=

Then, in the github url, change blob to raw. When the page is saved, the result should be a link that, when clicked presents a preview of the PDF as if it were ready to be printed.

Displaying External Images

Currently, it's not possible to display thumbnail versions of external images due to the underlying MediaWiki architecture (which makes a local thumbnail copy for uploaded images.)

However, it is possible to display non-thumbnail external images with a custom size. The syntax is

{{sized-external-image|400px|https://raw.githubusercontent.com/machineagency/jubilee/master/frame/assembly_instructions/wiring/duet2/duet2_frame_wiring.png}}

This syntax will display the image centered on the page in the desired width. Under the hood, this feature is calling custom CSS driven by a Template.

External image with a link and float position

An additional sized external image with link template is available that will automatically add a link to the source image and also adds an additional parameter (#3) to set the image float position (left, right, none). The default float position is "none" so the image will be centered if the third parameter is not included. If you only want a link to the image then do not include the third parameter (or set it to "none").

{{sized-external-image-with-link|600px|https://raw.githubusercontent.com/machineagency/jubilee/master/frame/assembly_instructions/wiring/duet2/duet2_frame_wiring.png|right}}

This syntax will display the image with an external link icon and will be positioned the right side of the page in the desired width.

Source Code and Preformatted Text

Wrap one-line GCode inside of <code> </code> blocks.

Example: "You can specify tool table offsets using the G10 L1 command."

Put many lines of GCode into their own block using the same <pre> </pre> blocks. Example:

; test square
F10000
G1 X0 Y0
G1 X10 Y0
G1 X10 Y10
G1 X0 Y10
G1 X0 Y0