Editing Guide

From Brevy
Jump to: navigation, search

This page displays "best practice" guidelines, brief "how to" descriptions, and help links for when editing on this site.

For Summaries

Please note that summaries should only be created with the appropriate form. This is found as the Create a summary link on the navigation bar (on the left of each page).

Editing Help

Depending on your needs, there may be a few links you might want to visit to get help editing:

For all else, please see the FAQ. Please note that, for summary editing, you will not need this information (or at least not to any high depth), as the form will handle most formatting for you or provide the brief explanations that are needed.

Tags and Subdomains

If you're having trouble coming up with the best subdomain or tags for your summary, we suggest checking out the Community Hub. As more people use Brevy, tips and suggestions can likely be found there.

Quick Summary Tips

Having trouble getting your quick summary down to 140 characters? Here are some helpful tips and examples:

  • Dealing with excessively long words - Try replacing these with ones more broadly characterizing the item. A couple of examples:
    • For the discovery of "Pikachurin," an "EGF-like, fibronectin type-III and laminin G-like domain-containing protein," you might write the protein's suggested role (a "dystroglycan-interacting protein") instead of its long title.
    • For a long chemical name such as "2,2-Bis-(4-(2-methacryloxyethoxy)phenyl)propane," you might instead consider it's category (a "(Meth)acrylate"), it's CAS number (or similar identifying number), or its intended purpose
  • Give the bottom line only - Focus on the results and conclusions rather than how the research was done unless novel techniques are a key point in the work
  • It doesn't have to be a full sentence - If you're grammar is a bit off, we won't complain, but keep it readable!
  • More to come!

We welcome suggestions for tips here. Please post them on this page's talk page, and we will consider migrating them here.

Summary Rationale

To help clarify Brevy's intent regarding summary length and presentation, here are a few Dos and Don'ts to keep in mind:

  • DON'T
    • Don't reproduce the abstract - Often, the abstract itself of a work is hard to quickly grasp due to including unnecessary information or jargon, or due to its paragraph nature. Avoid such pitfalls and take advantage of how Brevy breaks up the summary into easy-to-glance-at sections.
    • Don't try to substitute the paper - You may be tempted to include as much information as possible due to a certain paper being largely (for whatever reason) inaccessible. Resist this, as the summary is never intended to substitute the original author's work. You do the public better by providing them a short and easy summary to help them decide whether to pursue the original work further.
    • Don't presume the audience cares - This may sound odd, but by presuming the audience "doesn't care," you better understand the pressure to keep the attention of your audience with clarity and by being concise.
  • DO
    • Keep it organized
    • Get to the point!
    • Write in plain terms (even if writing to experts!)

Audience

Brevy breaks each summary up into two tabs-- the Basic version (intended for the general public), and the Expert version (intended for scholars and interested students).

Basic Version

The key goal for this section is to make otherwise obscure and inaccessible research open and understandable to the general public.

You should be striving here to write in such a way that a high school student could understand it. However, possible audience members might include:

  • Science journalists
  • High school classrooms
  • Undergraduate students
  • Business leaders
  • Interested public

Although some of the parties above will obviously have a better grasp of the material, you should cater to the lowest understanding level. Remember that the general public has likely pursued interests in fields different from what you are writing on and may have (understandably) forgotten high school or undergraduate knowledge through years of focusing elsewhere. Do not be afraid of "dumbing it down!" This is not a bad thing, but is rather a courtesy to your audience. If they want more advanced explanations, they will pursue it.

Expert Version

The key goal for this section is to primarily assist researchers or interested students in keeping track of relevant research or finding relevant research in an easy, expedient fashion.

Though calling this the "Expert" section, you should be striving here to write in such a way that an undergraduate student (in the same field) could understand it. To better understand this rationale, a few examples of the possible audience members who might read this section follows:

  • Science journalists
  • Interdisciplinary researchers
  • Undergraduate & graduate students
  • High school teachers seeking to better understand a topic
  • Researchers in a similar field
  • Interested public somewhat educated in the field

Although some of the parties above will obviously have a better grasp of the material, you should cater to the lowest understanding level. Remember that academic disciplines are often quite narrow and that, say, a general Biologist might not have the same background as a Molecular Biologist. Even here, Do not be afraid of "dumbing it down!" Your goal is not to supplant the research article, but rather to provide a brief overview of it and to help the reader decide whether to pursue the work further.

Note to Administrators

Although you will have the ability to "Edit Source" on summary articles, please resist this feature unless you are very familiar with how the wiki code works and have good reason to do so. If this is still needed, please make a note on the article's Talk page of your edit.

For Any Other Page

For pages outside of the main summary namespace (such as the Community namespace), guided editing forms may not be provided and may instead be replaced with a blank editing box. For editing in such pages, we suggest your check out our brief introduction to wiki concepts before editing there if you're unfamiliar with wiki editing. For all tips and "best practice" information beyond that of summaries, we suggest you check out the Community Hub page as the community will post information there over time.