Contributing to Sunbird Documentation
Contribution Guidelines Edit | Report
Contents[hide] |
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 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 and cheat sheet.
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? section and the Sunbird style guide 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 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: 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/ 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, 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
- Editing Sunbird Page
- Reporting an Issue
- Adding page or a section
- Review Process
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
|
 |
Step 2: Page opens on Github
|
 |
Step 3: Scroll to the Propose file change section
|
 |
Step 4: Comparing changes page is displayed
|
 |
Step 5: Open a pull request page is displayed
|
 |
Step 6: Review by team
|
|
Step 7: Revisit and Re-work (if needed)
|
|
Step 8: Content Acceptance
|
|
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
|
 |
Step 2: Page opens on Github
|
 |
Step 3: A form opens up
|
 |
How to add a page or a section?
To ensure that Sunbird users benefit enhancing the knowledge base is of primary importance
-
Follow all steps in the Reporting an Issue section
-
While adding the issue description, mention that you would like to contribute by adding a page or section before you submit the issue
-
Make a note of the issue number so that you can track your issue for future references.
-
The team assigns the issue to you and provides you with a link to an editable blank .md file.
-
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.