Skip to content

Documentation style guide

Jump to bottom
Martin Shetty edited this page Jun 21, 2022 · 22 revisions

No big files

Do not commit large binary (non-text) files into the repository.

The following are FORBIDDEN:

  • PDFs
  • MS Office documents
  • Original size & quality pictures
  • Exported STEP and STL files

File naming

Please follow these rules when naming files and directories:

  • all lower case for file name and extension
  • use underscore _ instead of space as word separator
  • exceptions for upper case are allowed, e.g. acronyms, manufacturer part codes
  • README.md generally appears as such in github. This is ok. Also helps grab your attention.

These rules are in effect because we have people working on different platforms and operating systems. For example:

  • Linux and macOS are case-sensitive, Windows is generally not
  • spaces in file names are more of a hassle to deal with in command-line tools and in markdown/HTML, where it must be substituted with either \ or %20. Not using it in the first place helps avoid this ugliness.

Following the above rules helps avoid frustrations for various users.

If you are using Windows, you might want to configure your file browser to explicitly show file extensions.

The GOOD ☺️

  • pneumatics_diagram.jpg
  • PCB_integration.md
  • oxygen_sensor_H578X2.ipt
  • README.md

The BAD 😒

  • Pneumatics Diagram.jpg
  • CONTROLLER.CPP
  • ImportedModel H5784X.ipt
  • OxygenInput_BrassPipeFitting_Adapter.ipt

Date format

Dates, wherever they appear, should follow the YYYY-MM-DD format, i.e.:

2020-05-04 for May the 4th of 2020

Separation with period is also ok, but may be problematic in filenames for some operating systems. Prefer dashes.

Currency

If prices are mentioned, the currency should be identified.

Do not assume dollars are always US. Say US$.

Measurement units

Prefer metric over "imperial". When providing length of wiring or physical dimensions of custom objects, describe in mm or cm. The exception is components that are nominally identified by their US standard designations, such as 1/4 NPT for a tapered thread.

Graphics

  • Prefer jpg ☺️ to png 😒. They take up much less space.
  • Ensure vertical resolution is ≤ 800 pixels.
  • If pictures are in a grid/chart, make sure their vertical resolutions are all equal. Also, in this case vertical resolution can be ≤ 600 pixels.
  • If you think users and contributors would benefit from a very high resolution image, consider uploading it to our Google Drive media section instead.
Clone this wiki locally