Difference between revisions of "Community Publication Portal"

From BRL-CAD
(set up an initial publication review pipeline for collectively making the fruits of our labor more succulently sweet. this should help publish brl-cad community activities more consistently & open.)
 
(add editing standards along with formatting standards)
Line 5: Line 5:
 
Note: if you see a comment indicating that a section is FROZEN, any changes you make in that section won't likely be included. If it is before the anticipated publication date (typically the third week of each month), send your changes to Sean (brlcad on freenode [[IRC]]) who may be able to incorporate them into the published edition.
 
Note: if you see a comment indicating that a section is FROZEN, any changes you make in that section won't likely be included. If it is before the anticipated publication date (typically the third week of each month), send your changes to Sean (brlcad on freenode [[IRC]]) who may be able to incorporate them into the published edition.
  
'''Formatting Standards:'''
+
'''Formatting & Editing Standards:'''
  
 
Feel free to fix if you see something non-standard.
 
Feel free to fix if you see something non-standard.
Line 14: Line 14:
  
 
* Titles and Section Headings are bold (achieved by placing text between three single quotes); each should be Title Case (Meaning UpperCase the Major Words)
 
* Titles and Section Headings are bold (achieved by placing text between three single quotes); each should be Title Case (Meaning UpperCase the Major Words)
 +
 +
* Use the serial comma.  One, two, and three; not one, two and three.
 +
 +
* Prefer first person for release notes, third person for everything else.
 +
 +
* Do not abbrev. words.
 +
 +
* Cite references and/or include hyperlinks.
 +
 +
* Keep it brief.
  
 
'''Distribution Channels:'''
 
'''Distribution Channels:'''

Revision as of 13:02, 8 December 2010

Welcome to the BRL-CAD community publication portal. This page is dedicated to the preparation and editing of community publications for BRL-CAD.

This is the place to learn what publications are proposed or upcoming, which are actively being worked on, and their individual editorial status. You are welcome and encouraged to contribute to any of the below articles so long as you uphold our formatting standards and publication process. New articles are welcome and encouraged to help share news about recent events or current activities taking place within the BRL-CAD community.

Note: if you see a comment indicating that a section is FROZEN, any changes you make in that section won't likely be included. If it is before the anticipated publication date (typically the third week of each month), send your changes to Sean (brlcad on freenode IRC) who may be able to incorporate them into the published edition.

Formatting & Editing Standards:

Feel free to fix if you see something non-standard.

  • Beginning quotations are italicized and placed between double quotes (wiki formatting requires 2 single quotes, space, double quote to achieve this)
  • All acronyms need to be defined (Like This) upon first use; further use can use the acronym only
  • Titles and Section Headings are bold (achieved by placing text between three single quotes); each should be Title Case (Meaning UpperCase the Major Words)
  • Use the serial comma. One, two, and three; not one, two and three.
  • Prefer first person for release notes, third person for everything else.
  • Do not abbrev. words.
  • Cite references and/or include hyperlinks.
  • Keep it brief.

Distribution Channels:

For release publications, follow HACKING. For everything else, distribute to the following:


Ready for Publication

These are articles ready for publication. Release notes should follow a release and get published within the first week of the month. Other publications should be scheduled one or two weeks later, ideally on the third week of the month.


Final Editorial Review

These should be "complete" articles. The author is done with the content and all that remains is a review of structure, grammar, voice, punctuation, and spelling. Images may be added as well.


Initial Drafts

These are incomplete articles being worked on. Most articles should be between 250 and 500 words (not counting tables, labels, and diagrams) before they have enough content to be considered complete.


Idea Hopper

These are ideas for interesting or useful publications. We need someone to at least write a draft.