Guidelines for Posting DevShare Content


Main Page | Discussion | Edit | History | Help | Switch to MediaWiki mode

DevShare is the central place on BIRT Exchange to find files and information contributed by other developers - including articles, code samples, tutorials, sample report designs, and more. We also encourage everyone to share resources they have found useful in developing and deploying reports by posting them on DevShare.

To facilitate posting of content in DevShare, the following loose "Style Guidelines" are provided. These are optional are are intended to encourage consistency, and help ensure that postings are as useful for the community as possible.

Contents

[edit]

Titles, Summaries and Descriptions

Generally, use Titles, Summaries and Descriptions to progressively promote and provide information on the content so that the user can decide if this is something that would be of interest to them. They would start by glancing at the Title, then the Summary, then click on the item to read the description and perhaps follow on to looked at the rest of the content or the linked article.

For this reason, it is important to be as descriptive as you can (but without being too wordy).

[edit]

Titles

Titles are used in the listings of DevShare items, as well as in heading for the detail for an item.

  • Titles should be as descriptive as possible within the limited space
  • Titles should be short enough (around 35 characters) to not be truncated in the lists
  • Use initial caps (example: Exploring BIRT Deployment Options)
  • Titles don't have to match the title of the reference content
  • Titles do not need to include author or source names
[edit]

Summaries

The Summary appears below the title in a list and can be longer than the title. They are key to providing "quick glance" information on what the item is about.

  • Always provide a summary -- they are very helpful!
  • Summaries are single line, full width (you have more space to work with)
  • Don't use a period "." at the end of a summary
[edit]

Description

The Description is shown on the detail page for an item. It should provide sufficient information for the reader to decide whether this is an item they would be interested in downloading/reading without actually having to go to the item.

  • An informal writing style is OK and encouraged
  • Descriptions can be as long as you want and include formatting such as bullets, links, etc.
  • Use "Verdana" and "Small" as the font, unless you have other specific needs
  • This is a technical site, so avoid marketing content and feel free to "talk techie"
  • If the item is a link, mention what the site they will be linking to is
  • If it's an abstract and link to external content, keep the description to 1 to 2 short paragraphs.
  • "BIRT" is OK. You don't need to use "Business Intelligence and Reporting Tools"
[edit]

Content Type

For DevShare, you must assign your item to a specific Content Type. Sometimes it's hard to figure out which one to use, and at the end of the day, there may not be one "right" answer for your particular item. To help you decide, here are some guidelines:

  • Designs & Code - This is article in DevShare that includes a file (or ZIP file containing multiple files) that could be code, a report design, a report library, etc. that can be run / compiled immediately. An example might be a report design that works against the BIRT example database.
  • Tips & Tricks - Typically one or more small technical pointers or How-Tos.
  • Tutorials - A more indepth, step-by-step article on that teaches the reader how to achieve a particular task.
  • Articles - An article that does not fall into any of the above.
  • Other - Well, this one kind of speaks for itself.
[edit]

Content

Content can be a range of items, from a link to an article on a site, to an attached PDF file, to a report design, to an article written and posted on DevShare, and anything else you might think of.

  • For multi-media content, we recommend that you use a hosting service such as YouTube to host the content, and then create a DevShare article that links to the content
  • If possible, mention what version of BIRT / e.Spreadsheet etc. the item works with / refers to

Retrieved from "http://www.birt-exchange.com/wiki/Guidelines_for_Posting_DevShare_Content/"

This page has been accessed 9,050 times. This page was last modified 00:10, 23 October 2007.