Tag Archives: english

Thumbnail

Contributing To MDN Web Docs




Contributing To MDN Web Docs

Rachel Andrew



MDN Web Docs has been documenting the web platform for over twelve years and is now a cross-platform effort with contributions and an Advisory Board with members from Google, Microsoft and Samsung as well as those representing Firefox. Something that is fundamental to MDN is that it is a huge community effort, with the web community helping to create and maintain the documentation. In this article, I’m going to give you some pointers as to the places where you can help contribute to MDN and exactly how to do so.

If you haven’t contributed to an open source project before, MDN is a brilliant place to start. Skills needed range from copyediting, translating from English to other languages, HTML and CSS skills for creating Interactive Examples, or an interest in browser compatibility for updating Browser Compatibility data. What you don’t need to do is to write a whole lot of code to contribute. It’s very straightforward, and an excellent way to give back to the community if you have ever found these docs useful.

Contributing To The Documentation Pages

The first place you might want to contribute is to the MDN docs themselves. MDN is a wiki, so you can log in and start to help by correcting or adding to any of the documentation for CSS, HTML, JavaScript or any of the other parts of the web platform covered by MDN.

To start editing, you need to log in using GitHub. As is usual with a wiki, any editors of a page are listed, and this section will use your GitHub username. If you look at any of the pages on MDN contributors are listed at the bottom of the page, the below image shows the current contributors to the page on CSS Grid Layout.


A list showing names of people who contributed to this page


The contributors to the CSS Grid Layout page. (Large preview)

What Might You Edit?

Things that you might consider as an editor are fixing obvious typos and grammatical errors. If you are a good proofreader and copyeditor, then you may well be able to improve the readability of the docs by fixing any spelling or other errors that you spot.

You might also spot a technical error, or somewhere the specs have changed and where an update or clarification would be useful. With the huge range of web platform features covered by MDN and the rate of change, it is very easy for things to get out of date, if you spot something – fix it!

You may be able to use some specific knowledge you have to add additional information. For example, Eric Bailey has been adding Accessibility Concerns sections to many pages. This is a brilliant effort to highlight the things we should be thinking about when using a certain thing.


A screenshot of the Accessibility Concerns section


This section highlights the things we should be aware of when using background-color. (Large preview)

Another place you could add to a page is in adding “See also” links. These could be links to other parts of MDN, or to external resources. When adding external resources, these should be highly relevant to the property, element or technique being described by that document. A good candidate would be a tutorial which demonstrates how to use that feature, something which would give a reader searching for information a valuable next step.

How To Edit A Document?

Once you are logged in you will see a link to Edit on pages in MDN, clicking this will take you into a WYSIWYG editor for editing content. Your first few edits are likely to be small changes, in which case you should be able to follow your nose and edit the text. If you are making extensive edits, then it would be worth taking a look at the style guide first. There is also a guide to using the WYSIWYG Editor.

After making your edit, you can Preview and then Publish. Before publishing it is a good idea to explain what you added and why using the Revision Comment field.


Screenshot of this field in the edit form


Add a comment using the Revision Comment field. (Large preview)

Language Translations

Those of us with English as a first language are incredibly fortunate when it comes to information on the web, being able to get pretty much all of the information that we could ever want in our own language. If you are able to translate English language pages into other languages, then you can help to translate MDN Web Docs, making all of this information available to more people.


A screenshot showing the drop-down translations list


Translations available for the background-color page. (Large preview)

If you click on the language icon on any page, you can see which languages that information has been translated into, and you can add your own translations following the information on the page Translating MDN Pages.

Interactive Examples

The Interactive Examples on MDN, are the examples that you will see at the top of many pages of MDN, such as this one for the grid-area property.


Screenshot of an Interactive Example


The Interactive Example for the grid-area property. (Large preview)

These examples allow visitors to MDN to try out various values for CSS properties or try out a JavaScript function, right there on MDN without needing to head into a development environment to do so. The project to add these examples has been in progress for around a year, you can read about the project and progress to date in the post Bringing Interactive Examples to MDN.

The content for these Interactive Examples is held in the Interactive Examples GitHub repository. For example, if you wanted to locate the example for grid-area, you would find it in that repo under live-examples/css-examples/grid. Under that folder, you will find two files for grid-area, an HTML and a CSS file.

grid-area.html


<section id="example-choice-list" class="example-choice-list large" data-property="grid-area">
    <div class="example-choice" initial-choice="true">
        <pre><code class="language-css">grid-area: a;</code></pre>
        <button type="button" class="copy hidden" aria-hidden="true">
        <span class="visually-hidden">Copy to Clipboard</span>
        </button>
    </div>
    
    <div class="example-choice">
        <pre><code class="language-css">grid-area: b;</code></pre>
        <button type="button" class="copy hidden" aria-hidden="true">
        <span class="visually-hidden">Copy to Clipboard</span>
        </button>
    </div>
    
    <div class="example-choice">
        <pre><code class="language-css">grid-area: c;</code></pre>
        <button type="button" class="copy hidden" aria-hidden="true">
        <span class="visually-hidden">Copy to Clipboard</span>
        </button>
    </div> 
    
    <div class="example-choice">
        <pre><code class="language-css">grid-area: 2 / 1 / 2 / 4;</code></pre>
        <button type="button" class="copy hidden" aria-hidden="true">
        <span class="visually-hidden">Copy to Clipboard</span>
        </button>
    </div> 
</section>
    
<div id="output" class="output large hidden">
    <section id="default-example" class="default-example">
        <div class="example-container">
            <div id="example-element" class="transition-all">Example</div>
        </div>
    </section>
</div>

grid.area.css


.example-container 
    background-color: #eee;
    border: .75em solid;
    padding: .75em;
    display: grid;
    grid-template-columns: 1fr 1fr 1fr;
    grid-template-rows: repeat(3, minmax(40px, auto));
    grid-template-areas: 
    "a a a"
    "b c c"
    "b c c";
    grid-gap: 10px;
    width: 200px;
    
    
    .example-container > div 
    background-color: rgba(0, 0, 255, 0.2);
    border: 3px solid blue;
    
    
    example-element 
    background-color: rgba(255, 0, 200, 0.2);
    border: 3px solid rebeccapurple;
    

An Interactive Example is just a small demo, which uses some standard classes and IDs in order that the framework can pick up the example and make it interactive, where the values can be changed by a visitor to the page who wants to quickly see how it works. To add or edit an Interactive Example, first fork the Interactive Examples repo, clone it to your machine and follow the instructions on the Contributing page to install the required packages from npm and be able to build and test examples locally.

Then create a branch and edit or create your new example. Once you are happy with it, send a Pull Request to the Interactive Examples repo to ask for your example to be reviewed. In order to keep the examples consistent, reviews are fairly nitpicky but should point out the changes you need to make in a clear way, so you can update your example and have it approved, merged and added to an MDN page.


Screenshot of a tweet asking for help with HTML examples


MDN looking for help with HTML Interactive Examples. (Large preview)

With pretty much all of CSS now covered (in addition to the JavaScript examples), MDN is now looking for help to build the HTML examples. There are instructions as to how to get started in a post on the MDN Discourse Forum. Check out that post as it gives links to a Google doc that you can use to indicate that you are working on a particular example, as well as some other useful information.

The Interactive Examples are incredibly useful for people exploring the web platform, so adding to the project is an excellent way to contribute. Contributing to CSS or HTML examples requires knowledge of CSS and HTML, plus the ability to think up a clear demonstration. This last point is often the hardest part, I’ve created a lot of CSS Interactive Examples and spent more time thinking up the best example for each property than I do actually writing the code.

Browser Compat Data

Fairly recently the browser compatibility data listed on MDN Pages has begun to be updated through the Browser Compatibility Project. This project is developing browser compat data in JSON format, which can display the compatibility tables on MDN but also be useful data for other purposes.


An example screenshot of the old tables on MDN


The Old Browser Compat Tables on MDN. (Large preview)


An example screenshot of the new tables on MDN


The New Browser Compat Tables on MDN. (Large preview)

The Browser Compatibility Data is on GitHub, and if you find a page that has incorrect information or is still using the old tables, you can submit a Pull Request. The repository contains contribution information, however, the simplest way to start is to edit an existing example. I recently updated the information for the CSS shape-outside property. The property already had some data in the new format, but it was incomplete and incorrect.

To edit this data, I first forked the Browser Compat Data so that I had my own fork. I then cloned that to my machine and created a new branch to make my changes in.

Once I had my new branch, I found the JSON file for shape-outside and was able to make my edits. I already had a good idea about browser support for the property; I also used the live example on the shape-outside MDN page to test to see support when I wasn’t sure. Therefore making the edits was a case of working through the file, checking the version numbers listed for support of the property and updating those which were incorrect.

As the file is in JSON format is pretty straightforward to edit in any text editor. The .editorconfig file explains the simple formatting rules for these documents. There are also some helpful tips in this checklist.

Once you have made your edits, you can commit your changes, push your branch to your fork and then make a Pull Request to the Browser Compat Data repository. It’s likely that, as with the live examples, the reviewer will have some changes for you to make. In my PR for the Shapes data I had a few errors in how I had flagged the data and needed to make some changes to links. These were simple to make, and then my PR was merged.

Get Started

You can get started simply by picking something to add to and starting work on it in many cases. If you have any questions or need some help with any of this, then the MDN Discourse forum is a good place to post. MDN is the place I go to look up information, the place I send new developers and experienced developers alike, and its strength is the fact that we can all work to make it better.

If you have never made a Pull Request on a project before, it is a very friendly place to make that first PR and, as I hope I have shown, there are ways to contribute that don’t require writing any code at all. A very valuable skill for any documentation project is that of writing, editing and translating as these skills can help to make technical documentation easier to read and accessible to more people around the world.

Smashing Editorial
(il)


Read this article:

Contributing To MDN Web Docs

Understanding Logical Properties And Values

In the past, CSS has tied itself to physical dimensions and directions, physically mapping the placement of elements to the left, right and top and bottom. We float an element left or right, we use the positioning offset properties top, left, bottom and right. We set margins, padding, and borders as margin-top and padding-left. These physical properties and values make sense if you are working in a horizontal, top to bottom, left to right writing mode and direction.

More – 

Understanding Logical Properties And Values

How to Increase Your Ranking by Mixing “Hidden” Keywords in Your Content

Comprehensive content, a tone of voice, storytelling, punchy texts, surplus value, social signals… While all these big words swallow up the digital marketing world today, one tiny detail sobs in the corner of your marketing strategy. Keywords. In 2018, search engines are smart and more concentrated on behavioral factors, so we sometimes belittle the role of keywords. SEO specialists know that anchors matter, but – afraid of keyword stuffing penalties – they struggle to broaden SEO far beyond this core instrument. They reshape market- and customer-defining descriptors for better rankings, so today we have tons of keyword types to include…

The post How to Increase Your Ranking by Mixing “Hidden” Keywords in Your Content appeared first on The Daily Egg.

Read this article: 

How to Increase Your Ranking by Mixing “Hidden” Keywords in Your Content

Contributing To WordPress: A Beginner’s Guide For Non-Coders

If you’ve been using WordPress for any amount of time, there’s a good chance you’ve come across the following statement: “Free as in speech, not free as in beer.’ If you haven’t, pull up a chair and let’s talk.
WordPress is a free and open-source software (also known as FOSS) project. The explanation of that could easily fill up a separate article, but the TL;DR version is that the software is free to download, use, inspect and modify by anyone who has a copy of it.

Follow this link:  

Contributing To WordPress: A Beginner’s Guide For Non-Coders

How To Internationalize Your WordPress Website

On September 30th, 2017, the international WordPress community united for 24 hours to translate the WordPress ecosystem. For the third time, #WPTranslationDay fused an all-day translating marathon with digital and contributor day events designed to promote the value of creating accessible experiences for global users, better known as “localization”.
As an open-source community, we should all strive to localize our open-source contributions. Before you can transcribe your digital assets though, you have to internationalize your codebase.

Read More:  

How To Internationalize Your WordPress Website

Thumbnail

A Sneak-Peek Inside The Southeast Asian Web Community

A few weeks ago, Vitaly Friedman (co-founder of this little magazine) and I had the pleasure to join the Mozilla’s Developer Roadshow, traveling through four countries in Southeast Asia in just two weeks. We visited cities that are buzzing with life and met people who share our passion for the web. Our mission: To get up close with the Southeast Asian web community. We wanted to learn how different local communities are compared to Europe and the US.

This article is from:

A Sneak-Peek Inside The Southeast Asian Web Community

Confessions Of An Impostor

Five years ago, when, for the first time ever, I was invited to speak at one of the best front-end conferences in Europe, I had quite a mixture of feelings. Obviously, I was incredibly proud and happy: I had never had a chance to do this before for a diverse audience of people with different skillsets. But the other feelings I had were quite destructive.
I sincerely could not understand how I could be interesting to anyone: Even though I had been working in front-end for many years by then, I was very silent in the community.

Taken from:  

Confessions Of An Impostor

The Fine Art of Landing Page Design: Using F & Z Patterns to Increase Conversions

In a saturated online world with an abundance of information, marketers are constantly battling for attention. You’ve likely read that online users have an attention span less than that of a goldfish. Therefore, the more organized and straightforward your strategy is for converting a lead, the better. Over the last couple decades, eye-tracking studies have been performed to ascertain where consumer’s eyes move when they land on a web page. Jakob Nielsen even authored a book Eyetracking Web Usability which analyzes “1.5 million instances where users look at Web sites to understand how the human eyes interact with design.” Landing…

The post The Fine Art of Landing Page Design: Using F & Z Patterns to Increase Conversions appeared first on The Daily Egg.

Read the article:  

The Fine Art of Landing Page Design: Using F & Z Patterns to Increase Conversions

Are Your Keyword Rankings You See On Google Correct?

Google Search Results Differ

Have you ever doubted Google? When it comes to the keyword ranking accuracy, we can be skeptical about rank tracker tools we use or SEOs we hired. But when we check rankings manually, we trust our eyes and Google. But you shouldn’t be so careless. Google is clever and agile. They have a massive list of factors that affect the search results they display for you. Even if you see your website in the Number 1 position, it doesn’t mean you really are on top of the world. Your customers may see a very different Top 10. Fortunately, you can…

The post Are Your Keyword Rankings You See On Google Correct? appeared first on The Daily Egg.

See original – 

Are Your Keyword Rankings You See On Google Correct?

Top 7 Ways to Build Brand Loyalty

Brand Consistent

Modern customers scour websites and research products they’re thinking of buying before making their actual purchase. When customers are 60% to 80% of the way down the funnel before they talk to anyone at your business, you can’t rely on traditional methods to generate loyalty. At the same time, fewer and fewer clients remain loyal to one specific brand. Loyal customers are profitable customers: repeat customers are cheaper to market to, spend more, and make more frequent purchases. Yet, only 27% of initial sales go on to become repeat customers. Companies need to invest in building loyalty among their customers….

The post Top 7 Ways to Build Brand Loyalty appeared first on The Daily Egg.

See original article here – 

Top 7 Ways to Build Brand Loyalty