DJB Guide: Report Writing: Difference between revisions

From Wikipedia of the Dark Brotherhood, an online Star Wars Club
No edit summary
m (Replacing a broken link with one to Markdown 102)
Line 69: Line 69:


* [[https://www.darkjedibrotherhood.com/shadow_academy/courses/86| Markdown 101]]  
* [[https://www.darkjedibrotherhood.com/shadow_academy/courses/86| Markdown 101]]  
* [[https://www.darkjedibrotherhood.com/news/markdown| Markdown Guide]].
* [[https://www.darkjedibrotherhood.com/shadow_academy/courses/100-markdown-102| Markdown 102]].


'''Abstract/Subheading:''' As noted in the post options, “Please provide a short summary or sub-heading for your report or news post” This Abstract is what will appear alongside the image of the News/Report on the front page. This should relate to the material within or be a small snippet of the content within. Snapshots do not use Markdown.
'''Abstract/Subheading:''' As noted in the post options, “Please provide a short summary or sub-heading for your report or news post” This Abstract is what will appear alongside the image of the News/Report on the front page. This should relate to the material within or be a small snippet of the content within. Snapshots do not use Markdown.

Revision as of 21:28, 20 August 2023

Introduction

The following documentation will cover the individual fields behind writing a basic report for the Dark Jedi Brotherhood.

While reports are expected from higher tier positions, they are not required at every level. Each Independent Unit tends to approach reports differently, with some units treating their respective positions differently. As a general rule of thumb and good habit, it is always best to check with your Clan or House Summit with questions about creating and posting reports.

________________________________________________________________________________________________________________________________________________

Report Types

A report is an informative piece of published documentation by a leader in the Brotherhood that aims to announce, share, and/or explain information relative to their respective position or society. Reports can be broken up into the following types:

Dark Council - Reports put out by the members of the Dark Council. These reports tend to focus on each Councilor’s area of expertise and the section of the club that they oversee.

Unit - Reports put out by the independent units that make up the Dark Jedi Brotherhood. This covers everything from entry level Battleteam Leader reports to top level Consul reports.

Society - Reports put out by society leaders that cover news and updates relative to their society (Wikipedia, Antei Combat Center, etc.)

News is anything that gets published to the Dark Jedi Brotherhood’s website and appears on the main page: https://www.darkjedibrotherhood.com. This means that any report that gets posted through the site administration is posted live as a newspost.

Reports are released by a leader on some kind of determined schedule cycle. For example, a report can be released bi-weekly, monthly, quarterly. Consistency is king, as the general membership relies heavily on the announcements, shared details, and explanations of changes/events to not only keep up with the changes in the club, but also to know why things are changing.

________________________________________________________________________________________________________________________________________________

Report Breakdown

Author: This field indicates the Author of the news/reports.

Unit/Position: This field indicates the position for which the member is posting content. If a member holds multiple roles it is important to ensure the correct Unit/Position is selected. In the example screenshot above, were I to post content for Arcona but select the role of Magistrate the material would not properly filter to Arcona.

________________________________________________________________________________________________________________________________________________

Category: This field indicates the intended content for the post and each member posting should ensure they choose the appropriate category. Mislabeling your Category could result in the poster being contacted to correct the post, or removal of the post.

Reports: The Report Category indicates any material for a specific group, this should be utilized for Battleteam, House, Clan, Magistrate, DC Assistant and Dark Council members will make use of this category when reporting to their members.

DJB News: The DJB News category should be for any material related to the Dark Jedi Brotherhood that doesn’t fall under a report. This could include announcements, available positions and used by the Dark Council to announce events or retirements.

Star Wars News: The Star Wars News category is intended to display important information for the Club (and will be shown on the front page for all members) related to developments or new information from Star Wars, this could include announcements including upcoming films, features, books, comics, etc.

Gaming News: The Gaming News category is for information related to changes or broadcasts related to the Brotherhoods gaming options. This could include topics such as upcoming Game nights, changes to supported titles or any other relevant information for the Club’s gamers.

Clan/House News: Similar to the Reports/DJB News, this category is used for announcements or information that doesn’t necessarily need a separate report. This could include open positions, retirements, announcement of title holders, or any other material that doesn’t include need an entire report.

________________________________________________________________________________________________________________________________________________

Target: Every News/Report should be categorized by whether members need to be logged in or if the material should be available for everyone. This is dependant of whether material within your news/reports is relevant to individuals who are not members of the Club.

________________________________________________________________________________________________________________________________________________

Title: This will indicate the title displayed on the main page once the News/Report is posted. Remember to use valid titles. Report titled do not need to include what position or unit they are for as that is displayed on the main page by default.

________________________________________________________________________________________________________________________________________________

Image: The Image field indicates the image that will displayed on the main page, in the example provided. The two options are the generic Dark Brotherhood image which should be generally used for any Club-wide News posts. Alternative options include Clan images, which should be used for Clan and House reports or news, or Role specific images such as the Dark Council.

Content: The body of the Report/News post this is where you will post the content of your report/news post. It is suggested to split the main body content into sections with the use of Markdown. For more info look at

Abstract/Subheading: As noted in the post options, “Please provide a short summary or sub-heading for your report or news post” This Abstract is what will appear alongside the image of the News/Report on the front page. This should relate to the material within or be a small snippet of the content within. Snapshots do not use Markdown.

________________________________________________________________________________________________________________________________________________

Tags: Tags are important to ensure that the News/Report appears for the accurate members and should include any material such as: Clan, Star Wars, Retirement, Promotion, etc.

Comment Method:

  • Local: Comments are posted locally on the website and are visible to everyone viewing them. Only registered members may comment locally. These are used for simple comments and are not suited for extended discussions.
  • Discourse: Comments are diverted to our [board] where members may engage more openly in discussions regarding the content of the News or Report. Discourse rules apply.
  • Disabled: No comments are allowed. Used sparingly and is generally discouraged unless there is a valid reason to do so.

________________________________________________________________________________________________________________________________________________

Preview News Content: This option allows you to preview the Content section of your post, this should be used with every post to ensure that your Markdown is accurate, review the material for any adjustments or errors that need to be corrected. Once you have made adjustments, use the preview option again until the post is ready to submit.

Preview News Item: This will allow you to preview how the post will appear on the Dark Jedi Brotherhoods homepage. This includes what image you have selected, the role you have selected as well as the Abstract/Summary section in how it will appear for members. Again as mentioned above, use this option and ensure all of your content is ready for submission.

Submit News: Prior to selecting this option, ensure your content is accurate, has been proofed, you have used the preview options below and are ready to post the content prior to Submitting.

________________________________________________________________________________________________________________________________________________

Writing the Report

When writing a report, there are a few different tools you can use. The most popular and common one — that is available to all members and completely free — is Google Docs. Google Docs allow you to easily share your reports with your supervisors or friends to get approval, feedback, or proofreading before posting. Alternatively, you can write your report in your word processor of choice with things like Microsoft Word, Apple Pages, or even a simple Word Pad.

Since the Dark Jedi Brotherhood website leverages Markdown coding for reports and news posts, you can alternatively — or additionally — take advantage of Markdown Preview editors. This allows you to type on one side of the screen and play with code while generating a preview of how it will look when posted. The Dark Council recommends:

  • Dillinger - One of the best preview tools available. Great save features, streamlined and easy to use.
  • Stack Edit - Full featured preview tool with example template.
  • Socrates - Super minimalist design. Easy to share with others.

Note: It is always wise to have your reports proofread by at least one other person. This can be a friend you trust, or your supervisor, but proofreading is strongly recommended.

Formatting

Formatting is the key to making your reports not only aesthetically appealing to a reader. It also makes them clear and easy to read. The more clear and concise your report is formatted, the better chance of not losing or confusing the members you want reading the report you worked so hard on!

As stated above, the website takes advantage of Markdown coding, which you can learn all about in the following Shadow Academy Exams:

Markdown 101 and Markdown 102.

It is highly recommended to complete these courses prior to writing a report. These courses are quick, informative, and educational. They will help create a foundation for your ability to write clear and easy to read reports.

For the purpose of focusing on the presentation of a report, this article will highlight the fundamental elements of Markdown that come in handy when writing a report.

Headers

Headers are important because they help break up information and create definitive starts and stops to topics throughout the report. Reports are read from top to bottom, so anytime you’re going to change subjects it is good to insert a header. The best practice with headers is to use a descending flow of sub-topics. The top heading should be the "parent" topic, something like Recognition. A sub-topic for that would be Promotions, since Promotions are a kind of recognition, similar to Awards.

Headers are handled by using a different count of pound (#) signs.

## Recognition
### Promotions!
### Awards!

You can also separate sections using the insert line function, also called a page break. You can trigger this by using 3 (or 5) consecutive dashes “---”. To make sure the formatting triggers, you need to make sure to include a line returns before and after the dashes (press enter/return above and then below).

Text.
---
More text.

Bullet Points, Numbered Lists

A good way to break up talking points or to make a list of information easier to read is by using bullet points or numbered lists.

  • You can use bullet points by using an asterisk (*) or a dash (-) followed by a space.
  • You can create a numeric list by using a number followed by a period (1.) followed by a space.
* Topic 1
* Topic 2
1. Topic 1
2. Topic 2

Usually, lists will trigger their formatting automatically. If for some reason they do not, make sure to add a double space after each point.

Hyperlinks, Bold, Italics

Using bold and italics is a great way to help emphasize points you want to drive home in your report. To bold or italicize something in Markdown, you can use the following code:

*Italics* / _Italics_
**Bold** / __Bold__
***Bold-Italics*** / ___Bold-Italics___

A hyperlink is a highlighted piece of text on a webpage that, when clicked, brings you to another web page. Hyperlinks are important because they can help easily route readers to information that might be useful. To insert hyperlinks in Markdown, you can use the following code:

[Hyperlink Text](http://webpage.com)

Inserting Images and Gifs

You can insert images and gifs into your reports. These are good to break up walls of text or to add levity. Just remember the old adage "all things in moderation" and try not to overuse images and graphics.

  • Note: Do not use the Assets options within Administration for GIFS/Images to include in your report, host these via an alternative source (imgur, etc) and use the proper markdown to include them in your report.
  • Secondary: Images will only appear if the url includes https (ex: https://wiki.darkjedibrotherhood.com would function / http://wiki.darkjdedibrotherhood.com would not).
![alt text](https:imageurl.png)

Important: Images and gifs must be “https” secure. Most popular images will use https, but if you run into issues you can use sites like imgur to host a secure image or gif.

Important: Images and gifs must include the filename in the url (.jpg, .png, .gif) in order to work. Using a .com, or any other website extension will not work.

Centering Images

While everyone has their own styles, the best practice and common style for reports is to center images. You can do this using the following markdown coding.

-> Centered Image <-

Anything else will default to Left-aligned. If you want to Right-align an image you can use the “->” arrow by itself.

-> Right-aligned Image

Conclusion

By following this guide, you should feel confident in either writing your first report, or implementing a new trick you learned into your existing reports. As with most skills, report writing becomes easier the more and more you do it. Don’t be afraid to ask questions. Don’t be afraid to have your superior or a trusted friend read over your report.

Useful Tools for Report Writing

  • Dillinger.io - Markdown preview tool.
  • Markdown 101 - SA Exam that teaches you how to use Markdown.
  • Markdown 102 - SA Exam that teaches you how to use Markdown.
  • Google Docs - Easily share writing and receive proofreading from peers.
  • Imgur - For hosting images securely with https.
  • Goo.gl - Url shortening.