Dangerous Prototypes blog style guide

From DP

Jump to: navigation , search

This is the style guide for the Dangerous Prototypes blog.

Contents

Contact form

General style

  • We are an editorial team, always use we, us, and our, not I, me, and mine.
  • No emoticons, smilies, :), etc.
  • How to quote a source: Via Make. (replace Make with the name of the website)
  • How to quote an image source: Image source.
  • The DIY electronics we post about are called 'hacks' or 'projects'. The people who make them are hacker or makers.
  • If you're talking about a project we do, it is always a 'project'.
  • A direct copy of an open hardware project using the same files, PCB, BOM is a clone. A compatible board with different PCB or BOM is a knock off.
  • Employees of big companies who hit the contact form can be called "PR Trolls" or "PR Droids".
  • Please don't use vulgar or swear words in posts.
  • Remove TM or C (trademark and copyright) from title and post text
  • Use SI standard units and number format: 10 MHz (ok), 10MHz (wrong)

Policies

  • Reviews: We can review anything, including freebies. Engineers sample, it's a normal part of the industry. Be sure to disclose any free stuff related to any post or review, especially if samples aren't available to everyone.
  • Kickstarter: It seems like everyone an their dog has a Kickstarter project. We should usually only post these if there is actual open licensed hardware now, such as a working prototype and Eagle files for download. Include a link to the project homepage, but please avoid linking directly to the Kickstarter page. The reason for this policy is because someone wrote to me and said they read about a project on our blog, gave money, and then the designer was unable/unwilling to complete it and ran off with everyone's money. Funder beware.

Titles

  • Make titles descriptive not cute, it's better for our search results.
  • Capitalize the first word and proper nouns.
  • No period
  • Do not capitalize every word:
    • OK: Super fast PIC microcontroller
    • Bad: Super Fast PIC Microcontroller

Pictures

Each post must have a picture.

  • Pictures should be 600 pixels wide with 40-80KB
  • Use this tool to size pictures.
  • Make sure the quality is good
  • When you upload the image in WordPress choose no alignment, no link
  • If there isn't a picture of the project:

Videos

Videos don't show up in RSS readers or on our Facebook page, try to use a picture at the top of the post if possible.

  • Put a picture at the top of the article, post the video after the break using the 'more' line.

Category and tags

  • Try to put each post in 1 or 2 categories, and give it a few tag words
  • Please use max 3 categories, 1 or 2 is better
  • Try to avoid the general categories (cool, interesting, etc) unless no other category fits

Some categories are reserved:

  • Prototype - reserved for DP project announcements
  • Project names - for anything related to that project (including external sites)

Extra links

If our project is mentioned in the post, please link it to the main wiki page.

If microcontroller is mentioned in the post (MSP430, PIC, AVR, ARM, etc), please link it to the quick start guide (if any).

If a 1-Wire, I2C, SPI, or other chip is mentioned, see if we have a Bus Pirate demo to link to.

Content

1. Link to the original article

  • Always link to the original article, even if we saw it somewhere else like Hack a Day.
  • If the post is about one of our projects, include the name in the first sentence and link to the project manual.

2. DP product sales line

  • If the post is about one of our projects, copy and paste a 'sales line' from the last post about it:
    • Example: Get a Bus Pirate for $30, including worldwide shipping at Seeed Studio. Adafruit also has the Bus Pirate and probe cables in stock and ready to ship.

3. Source

  • If we found the original article somewhere else, include a via link to the place we first saw it. Examples:
    • Via Hack a Day.
    • Via the forum. (include link to post)
    • Via the comments. (include link to comment)
    • Via the contact form.

Example flow of post

Post-link.jpg

Notes:

  • The title is descriptive and only the first letter is capitalized
  • It includes an image, sized to 600px, no link or alignment
  • The first sentence links to the actual webpage we're discussing, and links to the project from our site that it used
  • It includes the Bus Pirate sales line (where to get one, and how much it costs)
  • Since we saw this post at Hack a Day, it includes a via link to Hack a Day's post.

Wordpress tutorial

  • You will receive an email with your WordPress login name and password.
  • Login to WordPress here
  • DO NOT PUBLISH ON YOUR OWN, we'll review your first few posts together:
    • Set your finished posts to 'pending review'.
    • Send Ian an email with a link to the post preview, he will schedule the post

Step by step

Add a title

Add-title.jpg

Add a picture

Post-size-upload.jpg

Size and upload a picture. Picture should be 600 pixels wide, make the file size smaller a good range is 40-80KB.

Link to the original article

Post-sentence-link.jpg

Add an opening sentence with a link to the original article

Add a sales line

Post-sales-line.jpg

Add a 'sales line' at the end if the post is related to something we sell

Ex: Get your own handy Bus Pirate for $30, including world-wide shipping. Also available from our friendly distributors Adafruit, Open Source Control Systems, and eHaJo.

Add a 'via' link

Post-link.jpg

Add a 'via' link at the very end if we saw the original article somewhere else

Add tags and a category

Post-tags-category.jpg


Save the post as pending

Post-save-pending.jpg


Preview

Post-preview-link.jpg

Click the preview button to preview how the post will look, and send Ian an email with a link to the pending article

Post examples

This is not required!

These are just examples of our general formatting, this is not a requirement! Use your own personality and style. Write posts HOWEVER you like!

Forum post

Ex-forum-post.jpg

Opening sentence:

schazamp shared his ChronoBlot remake of the MaceTech ChronoDot in the project log forum:
  • Who posted it in the forum? schazamp. Be sure to link the schazamp's personal website (if any)
  • A link to the project on the main subject. ChronoBlot

Block quote:

I made this ChronoBlot a while back, but now that I have a Bus Pirate, I can easily test it out, set the clock, and set the alarm (and write scripts to help with that), so I’ll be updating it soon and wanted to track it on this projects forum.
  • A quote
  • Put it in a block quote (" button in WordPress)

Thanks and forum link:

Thanks schazamp! Via the forum.
  • Thank the person who sent the link
  • Add a link to the forum is not linked in the opening sentence: Via the forum.

Sales line:

Get your own handy Bus Pirate for $30, including world-wide shipping. Also available from our friendly distributors.
  • If our project is used add a copy of the sales line from the last post

Contact form post

Ex-ContactForm-post.jpg

Five cheap breadboard prototyping tips and tricks – list #2

Opening sentence:

Following up on their first list of tips, 43oh.com presents this second list of cheap breadboard prototyping tricks. SD card headers, LED diffusers and more.
  • Put the link of the original article in the opening sentence and the previous post link.

Block quote:

  • Optional quote from contact email, not used here

Thanks and contact form link:

Thanks opcode! Via the contact form.

Comment post

Ex-comment-post.jpg

Accelerometer controlled OLED 3D cube

Opening sentence:

Markus used an MMA7455L 3-axis accelerometer to detect the direction of the gravity in this cool demo:


Block quote:

I am using the MMA7455L breakout board to control a 3D cube displayed on a (SPI-modified Seeedstudio) OLED display.
My MMA7455L library is available in the forum.

Sales line:

Get the MMA7455L breakout board for $15 at Seeed Studio. Back in stock and shipping now.

  • If our project is used add a copy of the sales line from the last post

Thanks and comment link:

Thanks Markus! Via the comments.

  • Thank the person who sent the link
  • Add a link: Via the comments.

Followup post

Ex-comments-post.jpg

GPRS Arduino shield with SIM900 module

Opening sentence:

McZ tipped us to the GPRS shield using the new SIM900 cellular data module in a followup to our position location with GSM cellular post.
  • Put the link of the original article in the opening sentence and the previous post link.

Block quote:

GSM/GPRS 850/900/1800/1900MHz … for voice, SMS, Data, and Fax in a small form factor and with low power consumption. It is controlled via AT commands (GSM 07.07 ,07.05 and SIMCOM enhanced AT Commands), and fully compatible with Seeeduino/Arduino and Mega.

Thanks and comment link:


Part post

Ex-parts-post.jpg


MAX8934G dual-input linear Li-Poly battery charger

Opening sentence:

rsdio serves us another heaping helping of interesting parts today. Check out the MAX8934G dual-input Li+/Li-Poly linear battery charger:
  • You can write more, but it should have the same rsdio shares, with a link to the part in the first part of the post
  • Use the diagram as image

Block quote:

  • Monitors temperature to ensure safe charging and JEITA battery charging specification compliance
  • Charges safely by lowering the termination voltage and charge rate in hot or cold temperature
  • Includes all integrated MOSFETs
  • Delivers smart power path control to allow the system to be powered when the battery is completely dead

Thanks:

Thanks for the tip rsdio!
  • Thank the person who sent the link

App note post

Ex-appnote-post.jpg

App note: Hot-surface warning light with no external power

Opening sentence:

This design harvests heat energy to make electricity, and uses it to flash a warning light. Flashing LED hot-surface detector:
  • Put the link of the original article in the opening sentence
    • Link to a webpage if possible, not a PDF
    • Link on the topic keywords, not the manufacturer or "app note"
  • Use the diagram as image

Block quote:

Using a thermoelectric generator (TEG) to sense the temperature of a surface and a step-up switching regulator to boost the TEG output to a useful level, this warning circuit flashes a high-brightness LED when the surface temperature exceeds a threshold.
We’ve slowed the app notes a bit to accommodate the haters, but we thought this one is really cool.

Thanks:

Thanks rsdio!
  • Thank the person who sent the link

Check list

  1. Spell check title (may have to right click->check spelling)
  2. Spell check post text (use the HTML tab, spell check does not always work in the other tab)
  3. Check that proper names are spelled and capitalized correctly
  4. Website names and capitalization should be the same shown in the top left corner of a web browser
  5. Check post author. Usually it should be DP or Ian - only comments on Ian and DP go to the blogger mailing list
  6. Links should be on the main keywords or subject of the post
  7. App notes should link to a webpage if possible, not a PDF
  8. Links should cover the whole word, but not the period or a space
    1. wrong: Link. or Link.
    2. right: Link.