Prerequisites

If you want to contribute to the manual, you’ll need permission to edit.

TODO: set up https://www.netlifycms.org/

In any case, you’ll need to contact me with the email address associated with github, google, facebook, or twitter in order to edit because Jon needs to put such an email address inside a configuration file for you to gain editing powers.

If you are a Plucky user, before becoming an editor you should first realize that editors may embed videos or images from any site into this site. If that is going to be a problem for you, you may want to block video and images using the following commands.

Also keep in mind that some Plucky users are not fluent in English.

Rules

  1. Generally, use lower case hyphen-separated-words for the page name so that the url always contains lower case characters and requires no special escaping. Do not create pages with spaces in their names. For example, this page is “editing-the-manual” not “editing the manual”, and the title is explicitly set to the space-friendly name in the front-matter.

  2. Be consistent. Look at the documents that exist and attempt to format text in similar manner.

  3. Use sentence case for headings and titles.

  4. Do not duplicate substantial chunks of information on multiple pages. The manual has a search feature, and it is hypermedia. Use linking to point to the authoritative source rather than duplicating information. For example, instead of describing how to install Plucky on faq and on how to install, just describe it in on the latter, and link to it from the former. Exceptions to this guideline are appropriate for some pages, e.g. command line basics, where having several simple, introductory examples on one page can be helpful for new users.

  5. Avoid making whitespace-only changes, including combining or splitting up lines in the source. Every page edit is actually turned into a Git commit on the server, and whitespace-only changes make the output of tools like Git blame less useful.

  6. Use a consistent voice. Either the second person voice (“you”) or passive voice. Note that there is currently a mix of voices.

  7. Use up to 600 characters per line. In emacs, (set-variable 'fill-column 600).

  8. For screencasts, use 1024 x 768 for video resolution – this keeps videos slightly smaller and easier to see for those who have small displays. For format, prefer webm, then mp4. These rules can be broken sometimes: Jon used 1152x720 and m4v on one macOS video because he was in a hurry and didn’t know how to make a screencast except by using Quicktime. But if he had time, he would change this.

Tips for frequent editors

If you edit very frequently, you might want to ask Jon about non-browser access to the documents. That is how Jon updates lots of pages because it is a faster and more powerful way to edit many pages at once.

Also, take a look at the useful links below.

OS-specific sections

TODO: FIXME: this is out of date.

Some pages (e.g., how to install) have sections relating to specific operating systems. Since usually only one of these sections is relevant to the reader, JavaScript has been added that can automatically hide irrelevant sections on such pages, and give the reader a button to toggle the visibility of these sections. The possible OSes are:

  • Android
  • Chrome OS
  • iOS
  • Linux
  • Mac OS X
  • Windows
  • Windows Phone
  • Unknown
Last updated: 2022-10-20