contribution_guidelines.md

type	directory	title	page_title	description	keywords	published	allowSearch
landing	contributions	Contributing to Sunbird Documentation	Contributing to Sunbird Documentation	Guidelines about how to Contribute to Sunbird Documentation	Contribute, Code, Code contribution	true	true

It is our endeavor to ensure that Sunbird documentation is reliable and up-to-date. We welcome your collaboration to keep the documentation current, consistent and error-free. You can contribute by:

• Editing an existing page

• Adding a page or a section

• Reporting an issue

Sunbird manages documentation similar to how it manages code. The docs are in a Github repository{:target="_blank"} as Markdown documents. If you’re comfortable using Git and Github for source code or any other work, you’ll find editing and updating Sunbird documentation a breeze.

You may want to brush up on Markdown syntax. Here’s a handy Markdown guide{:target="_blank"} and cheat sheet{:target="_blank"}.

Writing Guidelines

Just as the Sunbird code follows coding standards and guidelines, the documentation has some simple conventions to follow. Please see the How to structure a document?{:target="_blank"} section and the Sunbird style guide{:target="_blank"} which follows to ensure the pages you submit are consistent with the rest of Sunbird's documentation.

How to structure a document?

Structuring your content is nothing but chunking the information into logical units. Developing a simple framework for your writing before you start can save considerable time and will prevent the text from meandering.

Unless the information is structured logically, it is not easily understood, usable or readable. Titles of the main sections as headings and subheadings within the text help readers navigate through the piece. Even if you do not desire to have the section titles in the finished piece, they will help you as an author to structure your writing to the desired framework.

There are no set rules to structuring your content. However, the following is a brief guide{:target="_blank"} that may be helpful.

Logical Hierarchy

Follow a logical hierarchy for your content. Most content is structured into subject, book, chapter, section, subsection, page; with subject being the largest chunk and a page the smallest. For example,

Sunbird > Installation > Installing Sunbird on Laptop > Prerequisites > Hardware Requirements

Page Structure

After you have decided the logical hierarchy for your content, structure each page with a logical hierarchy to make it readable and complete. Use headings and subheadings to build the logical structure of the page. For Sunbird, you can use three levels of headings.

Other than heading levels, you can structure the information on a page using paragraphs, tables, ordered (numbered) or unordered (bulleted) lists, infographics viz. diagrams, charts, images and notes.

Styles

You can use the following styles when formatting your document.

Titles and headings

Use short descriptive titles. Titles should be 80 characters or fewer. Avoid redundancy. For all main headings and subheadings use title case: only the first letter of the first word is capitalized. Everything else except proper names is in lowercase. (Sunbird is a proper name)

General text

Use short and appropriate sentences. Try to write in a very clear and concise manner. Avoid using jargons and words that are hard to understand. Be specific about who your audience is.

Sentence length

Keep sentences to 15 words or fewer. Do not be wordy. Long sentences are difficult to understand.

Blocks

Code segments are usually written in blocks. Use blocks if code segments are more than one line.

Contractions

Avoid using contractions, rather use the full word itself.

Procedure style

For sequential steps, use a numbered (ordered) list. For a set of options, use bullets (unordered list). When describing actions, avoid unnecessary words.

Punctuating lists

Precede an ordered or bulleted list with a sentence or phrase ending in a colon. For example;

In communities, you can：

• Get to know other Sunbird users

• Collaborate on projects in a small group

• Voice your opinion on a particular project

Begin each item with a capital letter (unless it is a product or company name that begins with a lowercase letter).

Note: Complete sentences in a list should have a period at the end. If a line item is not a complete sentence, do not use a period. If you are breaking a sentence into a list, as in the first example in this section (In communities), periods aren't necessary.

Be consistent, if possible, when writing the items in the list. Make them "parallel." In the first example, Get, Collaborate, and Voice are the same form of verb.

Numbers, Dates and Time

Numbers

• A billion is defined as an American billion: 1,000,000,000

• Thousands should be separated by commas, i.e 100,000

Dates

Express dates either in full (December 6, 2008) or use the proper ISO date format{:target="_blank"}: yyyy-mm-dd, as in 2008-12-06, depending on where it is being used. This may be unfamiliar to some users of American English, but the ISO standard is the widely-accepted date format for modern software.

Time

ISO 8601 uses the 24-hour clock system. The basic format is [hh][mm][ss] and the extended format is [hh]:[mm]:[ss], for example 13:47, or 13:47:30.

Hyphens

Use em dashes (HTML entity 8212, "—") for abrupt breaks in a sentence, to temporarily change subject within a sentence, for clarity, to draw attention to a point, or to signify the origin or author of a quotation.

• Donot use double hyphens; use the HTML entity.

• Donot place spaces on either side. There shouldn't be any space between the word or words next to an em dash and the en dash.

Use an en dash (HTML entity 8211, "–") to indicate a range of numbers or dates. (See www.alistapart.com/articles/emen/{:target="_blank"} for more information about the subject of dashes and hyphens.)

Links

When embedding a link in a documentation page, always make sure the link text describes the destination of the link. "Click here" is not a good description, because it does not tell the user where the link will take them. If you can't fully describe the destination of the link and still maintain good sentence flow, add a title tag. Title tags, used appropriately{:target="_blank"}, are important for making the pages accessible.

Voice

• Reinforce the Sunbird brand: Anything written at Sunbird.org becomes part of the Sunbird experience and conveys the Sunbird spirit.

Always try to be:

* clear, simple, and concise

* respectful, honest, and approachable

* engaging, welcoming, lively, and fun where appropriate

* Use ordinary, everyday language instead of words that sound more elevated.

• Know your audience: Tone of voice, use of jargon, and complexity of language should be appropriate for the type of page:

  • Major landing pages must be approachable and appropriate for a wide audience that could include beginners, company managers, designers, developers, business owners, first-time bloggers, tech-savvy entrepreneurs, educational organizations, or advanced Sunbird developers. Keep them in mind.
  • Use empathy: Put yourself in the place of the readers. Try to look at your text through the eyes of a variety of visitors.
  • You don't need the word "Please" in order to sound friendly. At times, it will be appropriate; usually, it will not. It sometimes comes across as condescending.

• Get them there: Ask yourself what visitors want to get done and help them get there quickly.

• Short isn't always best: Concise (brief yet comprehensive) is good, but shortness? It depends. What does the user expect and need?

• Open source not market-speak: Avoid fluffy sales talk. "We're great! Sunbird is great!" "We're the best!" These sentences are only believed by those who write them, not those who read them. Words such as "very, really, truly" tend to weaken a statement, not strengthen it.

• Edit and edit again: Strip away unnecessary words. Examine them. Is each one lively, direct, and doing a job? Or, is it empty or deadening? Because an informal voice is brand-consistent, complete sentences aren't always necessary. Eg.: This module reduces the time you need to set up a forum. This can be written as : This module reduces forum set-up time.

• Be clear about benefits for the reader: Sunbird is here to make people feel privileged and awesome at what they do. Using the word "you" can be powerful.

• In general, use active, not passive, voice: In active voice, the subject performs the action ("The dog ate the bone."). In passive voice, the subject is the target of the action ("The bone was eaten by the dog."). Don't twist sentences into knots trying to avoid this, though. Also, at times, passive voice emphasizes words that active voice would downplay. In that case, use passive voice, but, in general, use it sparingly.

• Avoid first-person: Avoid first-person (I, we, my, our) on editorial/landing pages. Use "Sunbird" instead. At times, because Sunbird is community-based, use "we" to sound inclusive or to reinforce the community concept.

• Balance the needs of new and experienced users. Provide links to additional or clarifying information new users may not know. At the same time, experienced users need quick steps.

• User-test your writing: Choose at least one person from your intended audience to make sure directions are clear and complete, and the tone is correct. User-testing is critical for sections like Modules and Documentation. If it is written for a new user with basic skills, you should test it on new users with basic skills. They should be able to achieve the final goal just by reading and following the directions, without asking you any questions.

Documentation contribution process flows

Click the links below to view typical workflows to collaborate for Sunbird documentation

• Contribute to Sunbird Documentation{:target="_blank"}
• Editing Sunbird Page{:target="_blank"}
• Reporting an Issue{:target="_blank"}
• Adding page or a section{:target="_blank"}
• Review Process{:target="_blank"}

How to edit an existing documentation page?

You can edit an existing page to correct inconsistencies or add missing information

Step	Screen
Step 1: Sunbird web page Click the Edit button from the top or bottom of the required Sunbird web page
Step 2: Page opens on Github Edit the content Complete all your edits
Step 3: Scroll to the Propose file change section The first text box automatically mentions that there is an update to the file name. Do not change the file name title If required further describe your changes in the second text box Click Propose file change button
Step 4: Comparing changes page is displayed Click Create pull request button
Step 5: Open a pull request page is displayed You can modify your previous comments, if required Click Create pull request button
Step 6: Review by team The team gets an alert about review the request and page edits The team will start review process Once the review process is complete, you will be notified in comments whether the suggested edits will be accepted or not.The team may suggest you to rework on the submitted changes discard them altogether as modifications
Step 7: Revisit and Re-work (if needed) You will get Github alert with the team’s comments regarding acceptance/rejection or there might be suggestions regarding the content Click Review changes button Take up the suggestions and re-work accordingly, once done Go to the pull request created for the file Click Commit button The same pull request is updated Repetition of Step :6 and Step 7 is required if content does not meet the reviewers requirements
Step 8: Content Acceptance If the content is found appropriate as per set guidelines, it's accepted Accepted content is then made live on the website

How to report an issue?

There could be inconsistencies in formatting, gaps in information that you notice (but cannot fix), etc. In such cases all you need to do is report the issue .

Before reporting any of these inconsistencies :

• Check whether the issue already exists by checking the issues present in issue tracker.

• If the issue has already been raised, check if the solution is given in comments .

• If either there is no solution to the issue raised , or the issue you are trying to raise is not present proceed with following steps:

Step	Screen
Step 1: Sunbird web page Click the Report button from the top or bottom of the required web page
Step 2: Page opens on Github The issue tracker opens on Github Click New Issue button
Step 3: A form opens up Fill in appropriate details viz. Title and Description Click Submit new issue The issue is logged in the issue tracker, with an appropriate issue number You need to remember your issue number for future reference and correspondence The team reviews and takes required action on the reported issue Note: You can track the progress and update on the reported issue using the issue number

How to add a page or a section?

To ensure that Sunbird users benefit enhancing the knowledge base is of primary importance

1. Follow all steps in the Reporting an Issue section

2. While adding the issue description, mention that you would like to contribute by adding a page or section before you submit the issue

3. Make a note of the issue number so that you can track your issue for future references.

4. The team assigns the issue to you and provides you with a link to an editable blank .md file.

5. Click the link and follow instructions from Step 2 viz Step 6 from the Editing an Existing Page section.

Note: When executing instruction step:5 , append the issue number to the file name title. For example; # 25

After your contributions are published on the Sunbird website, you will be included as a Sunbird documentation contributors list.