Socioeconomic Position of Disabled Persons in India: An Analysis of the Survey of Persons with Disabilities from Round 76 of the National Sample Survey Report

Socioeconomic Position of Disabled Persons in India: An Analysis of the Survey of Persons with Disabilities from Round 76 of the National Sample Survey Report

October 17, 2020
Raksheet Kota
The marginalization of minorities is a very contentious topic in our current political climate. We hear about the struggle against racial and sexual oppression on a daily basis and thanks to the efforts of activist groups and legislation changes, we have been able to make significant strides in these areas over the past few decades, promoting equality and understanding while silently admonishing the ignorance that previously ran rampant in our society. Contrary to popular belief, however, the largest minority in the world is not a particular race or sexuality but disabled persons, a group that is constantly left out of activists’ agendas (Raghava, 2011). This is particularly prominent in India which contains an astonishing 21 million of the world’s 56.7 million disabled persons. It can be said without question that disabled persons are undoubtedly disadvantaged in terms of their social position, especially in third world countries (Mehrotra, 2006). In the context of India however, this disadvantage adopts an entirely new perspective under the presence of deep-rooted and systemic cultural stigmas that oppress the disabled population. In addition to this, the highly competitive environment of Indian society, a natural byproduct of its population of over 1.3 billion people, creates striking boundaries across all denominations including caste, creed, age, gender, and wealth. Consequently, the sociodynamics of India is that society is often much more differentiated by region (largely due to language differences), leading to the decreased translation of federal laws into local areas and the overall inefficacy of placed legislation (Singh, 2014). The compounding of the aforementioned issues is what makes the socioeconomic condition of disabled persons in India a complex, multilayered issue that requires international attention.
Social Position of Disabled Individuals
The social condition of people with disabilities (PWDs) in India is not uniform, but varied among a number of auxiliary factors such as caste, religion, and gender. However, upon closer inspection certain trends can be observed. Overall PWDs are exposed to substantial social marginalization (Singh, 2014). Most literature attributes this low social perception to the deep-rooted social ideology of karma: the thought that misfortunes of one’s current life is due to divine punishment for mistakes made in the past life. In a study done by the South Asia Region of the World Bank, around 50 percent of rural respondents believed that disability is always a curse of god . This belief was especially prevalent in the vision subcategory of disability with more than 60 percent of respondents believing that their impairment was a result of divine condemnation (O’Keeffe, 2007).
One of the most impacted subgroups of disabled persons are children. The physical limitations of children with disabilities in India (CWDs) result in a significant impact to their immediate family and close relations. Mothers of CWDs have been shown to be more depressed, socially isolated, less competent, and less attached to their children compared to their conventional counterparts (Gupta, P. Mehrotra, & M. Mehrotra, 2012). Somewhat contradictorily, the level of stress these parents experience has been shown to have a direct correlation to their own social position. For example, those of higher prestige such as doctors experience increased parental stress compared to those of rural peasant status. In addition, female CWDs in particular are considered to be more burdensome and are consequently liable to marital discord, child abuse, and neglect (O’Keeffe, 2007). In order to combat these issues, it has been shown that families of CWDs resort to religion as well as traditional broadcast media to help them cope with their situation. A study done on rural Haryana emphasized the significance of established social networks in dealing with disability (Mehrotra, 2006). The mother is typically tasked with taking care of and indulging the child, while the father is tasked with exploring treatment options for him or her. Social networks both composed both of immediate family and established acquaintances act as social resources and facilitators of information, allowing for greater access to treatment.
In addition to children, women with disabilities are particularly neglected by society. Portrayal of disabled women in Bollywood movies is rare and in most cases the disability is acquired during the course of the film and is later solved or fixed rather than being acquired at birth and remaining in an attempt to normalize the actor (Jeffery & Singhal, 2008).Women with disabilities are shown to be more prone to unwanted touching, rape, or even physical abuse with this trend being even more apparent under the presence of mental disabilities (Swabhiman, 2005). Furthermore, studies have shown that only 50% of citizens believe that PWDs should be able to marry non-PWDs with most believing that disabled women (especially those with locomotor or mental disabilities) are not properly capable of having and caring for children. (O’Keeffe, 2007).
Economic Position of Individuals With Disabilities
Overall, the low social position of PWDs translates directly into their low economic capability. In a study done on rural regions of the states of Uttar Pradesh and Tamil Nadu, 80% of respondents agreed that students with vision, speech, or hearing disabilities should not be integrated into traditional schools (Kumar, 2005). This is an issue because integrated classes have been shown to provide CWDs with the most academic success and limiting their integration directly reduces their chance for economic success in a process known as capability deprivation. Additionally, as shown in a report by Seena Abraham (2013), participation in integrated classes have been shown to reduce negative self-stigma, thereby empowering and enabling the disabled student. She assesses that because 90% of all CWDs live in rural areas, lack of access to quality education has been a driving factor for the low overall economic empowerment of PWDs.
PWDs’ worldwide experience lower employment rates than non-PWDs, even in high income countries, with India showing a surprisingly average employment ratio. However, the employment gap varies based on type of disability (with mental retardation and visual impairment having the highest) and has steadily increased at all education levels over the past two decades presenting a cause for concern (Mishra & Gupta, 2006). Disabled men who are employed in paying jobs are often given a lesser salary due to a perceived lack of efficiency or productivity due to their disability. This assessment is justified, however by that fact that over one third of rural PWD men report being unable to work due to their disability as compared to only one fourth for women. Due to this perceived inconsistency PWD men are much more likely to be in variable wage jobs rather than steady wage salary employment with the opposite occurring in women (O’Keeffe, 2007). While a few Indian states have established employment right of disabled persons, a study by the Society for and Rehabilitation Studies New Delhi showed that only 58.7% of disabled respondents were aware of this.
Minorities are struck the hardest by economic inequality with scheduled tribes and castes (particularly dalits) showing the highest rates of unemployment and disability. Disabled women are often involved in informal/private sector work or unpaid work such as taking care of siblings, cleaning and cooking. These are both unaccounted for by economists and are partially responsible for the low economic status of PWDs; however, the PWD/non-PWD employment ratio of women is much higher than men. (Singh, 2014).
Previous Legislation Regarding Disability
Prior to the establishment of the rPWD act of 2016, legislation to aid PWDs was existent but lacked the implementation necessary to be impactful on the greater population. One of the largest factors of this issue is the inconsistent methods through which disability is defined and measured in India. This stems from the fact that the two largest national demographics surveys, the National Census and the National Sample Survey have radically different definitions for the major types of disability. For example the census is much more inclusive of people with glasses as visually disabled, whereas the NSS has less strict definitions for mentally disabled people. Despite having a similar number of total recorded PWDs, these records are hugely inaccurate as shown by the fact that if the stricter definitions of both records are used, 11.8 million disabled persons would be recorded, whereas if the looser ones are used, 26.5 million people would be considered disabled (Jeffery & Singal, 2008).
Beyond even the inadequacies of measuring disability, the implementation of aid policies in India was shown to be ineffective overall despite the government’s best efforts and intentions. Despite its outward appearance, India actually had a relatively robust support system for persons with disabilities centered around the Persons With Disabilities (or PWD) Act of 1995, the headlining piece of legislation that provides rights for PWDs in India which had its latest revision in 2016. The PWD act of 1995 is restricted specifically in its implementation of social protection programs. For example, food security for poor households is handled by the PDS (public distribution system) and the largest food security organization of the world. Nonetheless, about 1 percent of India’s GDP went into this program but 21 percent of all Indians were still undernourished. 94 percent of PWDs were not aware of reservation programs and only 0.1 percent have ever participated in a public works reservation program (O’Keeffe, 2008). The PWD Act of 1995 suggested unemployment allowance schemes but does not enforce them, resulting in basically nonexistent implementation on the local level. Additionally, a social pension were legally required to be provided to PWDs, but there are few numbers available to analyze and only 14 percent of all disability households were covered (O’Keeffe, 2008).
Another area in which legislation fell short is post-workforce life. Social segregation of the disabled is common because of deep-rooted cultural fears in Karnataka, India. One commonly suggested solution is community based rehabilitation, a system in which the mental and physical abilities of disabled persons are maximized through access to services and activities (Kumar, Roy, & Kar, 2012). While this is not currently in widespread use, there are many current measures being taken by the Ministry of Social Justice and Empowerment and Health such as the District Disability Rehabilitation center, the four Regional Rehabilitation Training Centers, the National Council for Handicapped Welfare, and the National Policy for persons with disabilities. Another suggested solution is a service-based method in which local and provincial officials cater services to the disabled in a particular region, requiring much coordinated effort.
Identified Gap in Research
Despite the extensive statistical profiling of PWDs in India, there has been a marked lack of analysis regarding the impacts of recent legislature on the socioeconomic conditions of individuals in India. As previously mentioned, the headlining piece of legislation that governs both the classification and the rights of disabled persons in India is the Rights of Persons With Disabilities Act of 2016 (rPWD Act). This revision of the previous Persons With Disabilities Act of 1995 was drafted following India’s participation in and ratification of the United Nations Convention on the Rights of Persons with Disabilities (UNCRPD) and was made to embrace the new global ideals of disability acceptance. Despite its flaws, the PWD act of 1995 did promote social welfare and reserved workspace for the disabled, but suffered from poor implementation and limited impact. The rPWD act of 2016 was designed in such a way to resolve these failures by featuring a much more comprehensive classification of disabilities (especially intellectual disabilities), enacting number of rights for the disabled, outlawing discrimination on the grounds of disability, and ensuring equal protection and legal capacity to the disabled.
A large part of the revisions that were made reflect the ideological shift from the point of view of the medical model to that of the social model. The social model argues that it is society that limits impaired people and that improvements must be targeted at a PWD’s surroundings rather than their medical condition (Reddy, 2011). Despite these welcomed reforms, most of the past literature regarding PWDs in India has pointed to the clear lack of implementation of national legislation due to harsh regional stratification made more severe by the existence of language barriers between states. Due to these reasons, oftentimes PWDs are not able to enjoy the benefits and reforms that were legally provided to them.
Though the sincere intentions of the rPWD act of 2016 are clear to see, whether or not these legislative changes have manifested themselves in a positive, accepting society has yet to be investigated thoroughly. Through my methodology I hope to evaluate the efficacy of the rPWD act of 2016 and measure it against its predecessor in order to analyze whether it has positively affected disability acceptance in India.
Research Methodology
Because of the nature of my inquiry, being a meta-analysis, I am the sole participant and conductor of said research. Seeing as I am primarily drawing from credited primary and secondary sources, and tabulating the provided information, there are no other participants in this study.
I specifically used the Survey of Persons with Disabilities from Round 76 of the National Sample Survey Report (Schedule 20). This data was collected from July-Dec 2018, so it can be used as a record of the status quo after the establishment of the Rights of Persons with Disabilities Act of 2016. I have also used the previous disability survey conducted by the National Survey Sample Organization (NSSO) in its 54th round in 2002 as a reference for disability data under the previous, less inclusive PWD Act of 1995. I also have made use of provided reference materials provided by the NSSO such as a copy of the physical survey itself and a detailed manual describing the intent and justification behind the inclusion of each individual section of the 2018 survey. Also, in order to analyze and explain these trends I often referred to “People With Disabilities in India: From Commitments to Outcomes” a report written by a team at the Human Development Unit of the South Asia Region of the World Bank.
Design and Procedure
For my analysis I analyzed shift in employment rates and average household income as this was one of the primary reforms of the Rights of Persons with Disabilities Act which provided employers with benefits if they reserved 5% or more of their workforce for disabled persons. I also deeply analyzed the section on social stigmas as the rPWD Act was created specifically to embrace new global ideals of disability acceptance with a shift from the archaic medical model of disability study to the more modern social model. By analyzing this data I hoped to see how effectively this shift in legislative ideology has been mirrored in rural Indian society. Finally the last section analyzed was school enrollment rates as the accelerated worldwide push for integrated classes for disabled kids (particularly in the last decade) was intended to greatly increase on the enrollment and academic success of children with disabilities in India.
Analysis of Statistical Data
In regards to the specific method of analysis that I used to analyze the previously mentioned points, I started by comparing survey response percentages for employment, social perception, and school enrollment rates to find specific factors that were significant. I specifically assessed this significance as factors which saw a 20 percent or more change in response frequency between the 2002 and 2018 surveys or a factor that varies by more than 30% between PWD and non-PWD populations. Upon gathering these statistically significant data points, I set out to explain these trends through referring to published individual research, specifically “People With Disabilities in India: From Commitments to Outcomes”, a report written by at team at the Human Development Unit of the South Asia Region of the World Bank.
One problem I originally anticipated is finding current and accurate information regarding PWDs in India. Although I did have access to recently published public survey reports following 2016, the most recent survey conducted by the National Sample Survey Organization (NSSO) before the passage of the rPWD Act of 2016 was taken in 2002 and therefore might be flawed or in some cases obsolete. Additionally this dataset was somewhat notorious within the scientific community for its inconsistencies with the (at that time recent and equally important) National Census of 2001. For example the census is much more inclusive people with glasses as visually disabled, and the NSS has more stringent definitions for mentally disabled people. If the stricter definitions of both records are used, India would have 11.8 million disabled persons, whereas if the looser ones are used, 26.5 million people would be considered disabled in India. However, the manual for the newer 2018 study does note these previous inconsistencies and states its intentions for a more fair and inclusive study.
notion image
Data taken from 2018 NSS Survey of Persons with Disabilities (NSSO)
The prevalence of disability has shown a generally increasing trend over last 50 years. This trend has remained constant for both male and female populations as well as urban and rural populations with the important distinction that urban and female populations generally experience lower rates of disability. The particularly large increase in disability rate between the 58th and 76th round NSS surveys denotes the increasing importance of disability specific aid and highlights the importance of the reforms put for by the RPWD act of 2016. In addition, regarding onset of disability, the percentage of PWDs who recently (within the last 365 days) became disabled has increased slightly whereas the percentage of PWDs who were disabled since birth has decreased slightly. This could potentially point to an increase in hazardous working conditions or automobile accidents over the past decade.
notion image
Data taken from 2018 NSS Survey of Persons with Disabilities (NSSO)
Labour force participation rate has gone up significantly in males (about 25 percent in males) but remains low in females due to external factors. This progress is most likely due to strong incentivization in the rPWD act through the equal opportunity act (Section 21). In addition, when compared to the 58th round survey, the disparity between the historically higher rural unemployment rate for PWDs and the urban unemployment rate for PWDs has decreased suggesting increased disability acceptance in the workforce for rural areas. Additionally, it is important to note that employment is one of the few areas in which rural PWDs are favored over urban PWDs must likely due to the ample availability of agricultural labor jobs with a low skill barrier to entry.
notion image
Data taken from 2018 NSS Survey of Persons with Disabilities (NSSO)
Promotion of integrated classes internationally as well as disability-specific aids and grants over the last 15 years has resulted in a marked improvement in literacy rate for CWDs (rPWD act section 16) while lowering the enrollment of CWDs in “special schools”. Despite these positive changes, the percentage of PWDs who have completed secondary education remains egregiously low, especially for rural females of whom only 8.2 percent of PWDs completed secondary education or above. The low percentage of vocal/technical training for children, especially those in rural areas also remains concerning. In addition, the large disparity between male and female education remains alarmingly large. This, however can be attributed to native beliefs on the role of women rather than anything disability-specific. Enrollment in vocational/technical training, on the other hand, while improving slightly in urban areas remains alarmingly low (1%-2.2%) across the board. These low participation rates point to a poor implementation of specialized training services for the disabled coupled with low awareness regarding these facilities and their potential benefits. Additionally, enrollment data remains the largest separation factor between urban and rural PWDs with urban areas having 40 to 100 percent more participation than rural areas based on degree of education. This disparity, coupled with the previous observations regarding female and male education rates, clearly demonstrate that education rates of PWDs in India are governed by systemic cultural phenomena such as gender roles and the urban-rural divide, thereby explaining the limited effectiveness of disability-specific legislation in this area.
notion image
Data taken from 2018 NSS Survey of Persons with Disabilities (NSSO)
The percentages of PWD’s, both male and female, who have consulted a doctor has improved considerably over the last 15 years. However, further specialized treatment percentages remain low and have only exhibited meager progress despite the healthcare reforms mentioned in Chapter 5 of the Persons with Disabilities act. A large portion of this lack of treatments can be attributed to accessibility. Despite the majority (69%) of disabled persons living in rural areas, sanctioned posts for medical specialist in rural areas have exhibited a 82 percent vacancy rate. Patients who are not able to find appointments are usually referred to tertiary hospitals located in major cities, most of which remain inaccessible to rural residents due to factors such as large travel distances and high operation costs.
Limitations of Results
It is notable that the NSS 58th round and 76th round used different operational definitions for disabled persons as well as slight differences in reference period and classification of disabilities. The earlier survey defines a PWD as a “person with restrictions or lack of abilities to perform an activity in the manner or within the range considered normal for a human being was treated as having disability” whereas the later one adopted the more progressive social focused definition of “a person with long term physical, mental, intellectual or sensory impairment which, in interaction with barriers, hinders his full and effective participation in society equally with others”. Additionally while the 58th round survey did take precautions to exclude temporary or recent ailments from their disabled group, the 76th round survey concisely defined “long term impairment” as one that has occurred for a period of more than 12 months with exceptions being made for certain conditions such as amputation, acid attack, haemophilia, multiple sclerosis, Parkinson’s disease, etc. Finally, the earlier survey classified disabilities into 6 general categories: mental illness, mental retardation, visual, hearing, speech, and locomotor whereas the later survey adopted a more complex classification scheme of 22 subgroups sorted into 8 overarching groups: locomotor, visual, hearing, speech and language, mental retardation, mental illness, other, and multiple. These inconsistencies (definition, reference period, and classification) could potentially serve as confounding variables, potentially delegitimizing any attempt of comparison between the two surveys. However, these small changes in definition or classification overall have a low impact on the data barring uncommon fringe cases such as those disabled within the last 12 months but not “recently” as defined by the NSS 58th round survey. Noting these minor inconsistencies we may proceed with caution to the analysis.
Despite the positive trends exhibited throughout the last two decades in terms of disability rights and acceptance, the results of the analysis of the NSS survey of people with disabilities demonstrates definite room for improvement. The implications of this assessment is that in certain areas the rPWD act of 2016 may not have been sufficient or well implemented enough to bring about the intended degree of change. One specific area where this is prevalent is higher level preventative measures such as vocational/technical training as well as specialized treatment for PWDs, both of which remains fairly uncommon in India today. The other major area where these changes have fell short are employment rates which despite improvement still pale in comparison to that of able-bodied people. Those that are employed are more likely to be in low-skill primary or secondary sector jobs as evidenced by the higher employment rates in rural areas. The skill barrier exists as the most visibly apparent barrier to employment in higher sector jobs with only 31 percent of PWDs having achieved a secondary education and a mere 1.2 percent achieving a technical education. The fact that the steadily increasing literacy rate of PWDs hasn’t been reflected in employment trends indicate that the competitiveness of the Indian job market also serves as a barrier to the employment of PWDs. While up to one third of PWD men are unable to work due to their impairment, the stark contrast of employment rated between the disabled and able-bodied populations entails the continued existence of cultural stigmas surrounding PWDs in the economic sphere.
Despite definite policy driven improvements, there are still certain grounds to still be made when it comes disability acceptance and empowerment in India. However, it does suffice to say, given the measured progress made in the two years of the bill’s existence, that the Rights of Persons with Disabilities act of 2016 has accomplished its goal: “To promote, protect and ensure the full and equal enjoyment of all human rights and fundamental freedoms by all persons with disabilities, and to promote respect for their inherent dignity” as stated in article 1 of the United Nations Convention on the Rights of Persons With Disability. Despite these results, the plight of the disabled remains a paramount issue in Indian society. Enrollment and education rates of PWDs have shown definite improvement over the past 15 years, but when compared to the general population, they still remain disparagingly low. As such, the battle for disability rights in India is far from over, requiring a radical shift in perspective that as of current is not reflected in Indian society. One proposed legislative change that could aid this transition is the inclusion of PWD representatives in government decisions regarding disability rights. As of current the majority of decisions made regarding disability-be it private or public-are made by able-bodied people (Shrivastava 2018). By giving the disabled a voice in these processes they are more likely to reflect a sincere effort to better the lives of the disabled rather than a dishonest imparting of power to a disgruntled minority. In addition to this change I would recommend that future legislation mandate specialized vocational training for CWDs in elementary education in order to lower the skill barrier, opening up job opportunities for PWDs as mere literacy does not seem to be representative of employment as of recent. One final change I would propose is the implementation of bi-annual disability awareness seminars in all public elementary and secondary school in order to inform CWDs of the rights and facilities available to them as well as reinforce to children that CWDs are no different than able bodied kids and vice versa. Hopefully such a change could instill CWDs with the confidence to pursue education and employment opportunities despite personal challenges. As evidenced by the great humanitarian efforts of the past, societal acceptance is not an overnight change but the result of years of focused drive towards activism and awareness. Moving forwards into the new decade we can only hope that we will once again pick up the reins of equality to put an end to the oppression of the disabled.
Further Research
Overall, the ever-increasing percentage of PWDs in India prompts the need for further research in a number of key areas. Some major subjects include cause of disability, frequency of specialized aid at different socioeconomic profiles, and awareness of national policies regarding aid for those with disabilities especially those indicated in the more recent rPWD act of 2016. The publishing of accurate information on these topics will serve to better determine and begin the fix the current barriers to further disability aid for the general population. With the frequency of PWD’s showing a general increase within the last 50 years and especially in the last 20, these questions need to be answered now more than ever. In addition, research regarding awareness continues to be a critical component of disability acceptance moving forwards. Education regarding the plight of the disabled population as well as the specific aid opportunities that are presented to them can help PWDs gain access to the help they need to cope with their condition and can help even non-PWDs regard the disabled population with the respect and consideration they need to thrive. Only through such widespread awareness can such necessary age-old stigmas as disability being the cause of divine punishment be overturned, a necessary prerequisite to attaining global disability acceptance moving forwards.
Abraham, S. (2013). Quality of life among adolescents with physical disability undergoing
integrated education. Research Journal of Recent Sciences, 2(5), 1–5.
Gupta, V., Mehrotra, P., & Mehrotra, N. (2012). Parental Stress in Raising a Child with
Disabilities in India. Disability, CBR & Inclusive Development, 23(2), 41–52. doi:
Jain, A. (2012). Researching (with) people with disabilities: Reflections from the research diary.
Indian Anthropologist, 42(1), 55–70. Retrieved from
Jeffery, R., & Singal, N. (2008). Measuring Disability in India. Economic and Political Weekly,
43(12/13), 22–24. Retrieved from
Kumar, S. G., Roy, G., & Kar, S. S. (2012). Disability and rehabilitation services in India: Issues
and challenges. Journal of Family Medicine and Primary Care, 1(1), 69.
Mehrotra, N. (2006). Negotiating Gender and Disability in Rural Haryana. Sociological Bulletin,
55(3), 406–426. Retrieved from
Mishra, A., & Gupta, R. (2006). Disability Index: A Measure of Deprivation among Disabled.
Economic and Political Weekly, 41(38), 4026–4029. Retrieved May 2, 2020, from
National Sample Survey Organization (NSSO) Ministry of Statistics and Programme
Implementation Government of India, (2003) Disabled Persons in India, NSS 58th round (July — December 2002) Report №485 (58/26/1) December 2003, New Delhi.
O’Keefe, P. (2007). People with disabilities in India: From commitments to outcomes. Human
Development Unit, South East Asia Region, The World Bank, 157 pp. 21–32,
Reddy, C. (2011). From Impairment to Disability and Beyond: Critical Explorations in Disability
Studies. Sociological Bulletin, 60(2), 287–306. Retrieved from
Singh, P. (2014). Persons with Disabilities and Economic Inequalities in India. Indian
Anthropologist, 44 (2), 65–80. Retrieved from
Shrivastava, A. (2018, August 1). Disability in India Is Still All About the Able. Retrieved from
The Persons with Disabilities (Equal Opportunities, Protection of Rights and Full Participation)
Act. 1995.
The Rights of Persons with Disabilities Act, 2016, Gazette of India (Extra-Ordinary); 28
December. 2016.
The best techniques for sharing code snippets and screencasts that will help propel your open source projects to success.


Creating your own open source projects can be extremely rewarding, but it can be hard to break through the noise and get other developers to trust and use your software. You can gain a lot of ground by following common best practices like including solid documentation, adding unit tests, integrating with a CI/CD oriented towards open-source projects (like travis-ci or circle-ci), and enforcing consistent style conventions.
One of the most effective and easiest ways I’ve found to make open source projects really stand out from the crowd is adding quality screenshots or animated demos. Whenever I see this attention to detail, not only does it prove to me that the author cares about the project, but it’s the absolute fastest way to convey what the project actually does.
A picture is worth a thousand words. — Cliche saying that’s totes relevant
Including quality screenshots and demos is becoming an increasingly important part of what I’d call Developer UX, that is the flow a prospective developer takes from considering adding your project as a dependency all the way through successful integration and future maintenance.
Towards that end, we’ll be looking at three common use cases for improving the developer UX of your open source projects with media:
  • Static code snippets (images)
  • Animated code demos (GIFs or animated SVGs)
  • Project screencasts (videos)

Static Code Snippets

Sharing small bits of static code is definitely the most common and important use case on this list. Every open source project’s readme should include some easily parseable example usage snippet, so let’s start there.

GitHub-Flavored Markdown Snippets

At the easiest end of the spectrum, GitHub allows syntax highlighting in markdown code snippets. Hopefully, this style of embedding is familiar to you, and if not, I would definitely recommend starting here.
const pMap = require('p-map') const got = require('got') const sites = [ getWebsiteFromUsername('sindresorhus'), //=> Promise '', '', '' ] const mapper = el => got.head(el).then(res => res.requestUrl) pMap(sites, mapper, { concurrency: 2 }) .then(result => { console.log(result) //=> ['', '', '', ''] })

GitHub Gists

The code snippet above also provides an example of an extremely popular way of sharing static code snippets via GitHub Gists, which have the following advantages:
  • Linkable
  • Support versioning
  • Support discussion via comments
  • Syntax highlighting


Markdown snippets and GitHub gists are both useful, but if you really want to make your code pop, then look no further than Carbon.
Image Credit: Carbon
Image Credit: Carbon
Carbon is a very popular open source project that allows you to easily create aesthetically pleasing code screenshots, along with a plethora of customization options and community plugins. It’s a great choice for making a hero image standout in your readme, increasing engagement on social media, or for writing engineering-related blog posts like this one 😛.

Animated Code Demos

Including a high quality, inline demo that quickly demonstrates your project’s core use case is the single most important suggestion I have to give.
There are a ton of different ways to go about creating these types of demos, however, so I’d like to discuss what I’ve found to be the best approach here.
Asciinema is a free tool that lets you record and share your terminal sessions, the right way.
Asciinema provides a lightweight, purely text-based approach to terminal recording, which allows you to make lossless recordings that can then be shared directly or rendered to animated SVG, animated GIF, or video. It surprised me just how many popular open source projects on GitHub make use of Asciinema — I would highly recommend checking it out.
Example Asciinema screencast converted to a GIF (credit: create-react-library) Note that the quality of this embedded GIF is much lower than the animated SVG in the linked readme as discussed below.
Example Asciinema screencast converted to a GIF (credit: create-react-library) Note that the quality of this embedded GIF is much lower than the animated SVG in the linked readme as discussed below.

Animated SVG or GIFs?

We all know GIFs are a horribly inefficient, lossy format, but let’s dig a little deeper into this particular use case.
Compare the above embedded screencast gif to the animated SVG of the same screencast from the readme. It’s difficult to embed an inline comparison side-by-side, but the animated SVG is significantly sharper and smaller, coming in at 73kb vs 4.4MB for the lower quality GIF.
Why is this even a discussion then? Well, you can’t exactly include custom HTML in a Medium blog post, now can you? And for that matter, there are a lot of places where using custom animated SVGs won’t fly, and for the foreseeable future, GIFs will live on as a fallback for those use cases. But open source authors, please consider using animated SVG versus GIFs for your GitHub projects!
There are some very popular open source projects on GitHub that have started using more efficient animated SVGs for their demos, such as create-react-app, but in general, you’ll find GIFs to be much more common.
Here's a few examples of using the excellent svg-term-cli to generate our lossless animated SVG.
# generate animated SVG svg-term --cast 'fxdtpprue51QZkeViQurqPg8V' --out demo.svg --window --width=80 --height=24 --term=iterm2 --profile=Snazzy # generate single frame SVG at 20 seconds into the screencast svg-term --cast 'fxdtpprue51QZkeViQurqPg8V' --out screenshot.svg --window --width=80 --height=24 --term=iterm2 --profile=Snazzy --at 20000
It’s important to note that when discussing animated SVGs, we’re really talking about embedding an HTML snippet into GitHub-flavored markdown that links to an SVG file encoded with each frame as an SVG group and the animation defined via CSS keyframes (example SVG source).
<p align="center"> <img width="600" src=""> </p>
Insert this HTML snippet into any GitHub-flavored markdown file to embed the linked animated SVG with optimal sharpness and low size overhead compared with a comparable GIF.
For reference, here is the screencast from create-react-library we’ve been using as an example in several different formats:

Capturing and Optimizing GIFs

Asciinema is great for terminal-based recording, but what if you want to record a UI component or website? Well, my first and foremost answer here is to always include a usable demo if possible alongside your project, especially if it’s a frontend web project. It’s really easy to get started with GitHub Page’s free hosting!
If you do want to include a GIF, I’d recommend using either GIPHY Capture or Kap to record your screen and output a GIF. Alternatively, if you have a video recorded from another source, I’d recommend using Gifski to convert the video to an as-optimized-as-possible GIF for ease of embedding.
<!-- html snippet customizing embedded gif --> <img src="" alt="example prompt" width="499" height="103" /> <!-- raw markdown can also be used to ambed a gif --> ![](
Quality demo GIF embedded in readme using the snippet above. (image credit: prompts by terkelg)
Quality demo GIF embedded in readme using the snippet above. (image credit: prompts by terkelg)

Project Screencasts

If your project is becoming more involved or you’re launching your project to a wider audience, including walkthrough video(s) can really help with user onboarding and support.


My go-to screen recording software is ScreenFlow, which is not cheap at $129, but gives you a lot of powerful, quality tools for the price, including precise rectangular screen recording, video and audio track mixing, audio voiceovers, transition effects, and more. This type of screencast is quite a bit more complicated than the screenshots and terminal session recordings we were looking at earlier.


Developer UX is important for promoting and marketing your work, which can in turn lead to very real consequences, as getting noticed for your open source contributions is definitely one of the best ways to gain notoriety and land big job opportunities as a software engineer.
I hope some of the techniques I’ve covered help you to promote your open source projects. If you’ve found this article useful and end up creating a snazzy screenshot or animated demo, add a comment linking to your project and let me know!
And as always, don’t forget to spread the ❤️… in the form of beautiful coding demos, of course!

Follow me on twitter for more awesome stuff like this @transitive_bs