Unlike writing code (which is what developers signed up to do), documentation (which we didn’t) has to and should be easily digested by everyone. Technically, we have to translate a machine language (code) into a language that is understandable to humans, which is tougher than it sounds.

Although it can be a real burdensome, writing the documentation is important and will deliver advantages for your users, your colleagues, and especially yourself.

Recommended Reading:Learning Programming: 10 Misconceptions That Are Not True

Good Documentation Helps Users

Documentation helps the reader understand how a code works, obviously. But many developers make the mistake of assuming that the users of the software will be proficient. Hence, the documentation may be thin material, skipping a lot of the essentials it should have contained from the beginning. If you are savvy in the language, you can figure things out on your own initiative; if you are not, then you are lost.

Documentation intended for users usually consists of practical use or the “how-to”. The rule of thumb when creating documentation for general users is that it should be clear-cut. Using human-friendly words is preferable to technical terms or jargon. Real use examples will also be greatly appreciated.

A good layout design would also really help users scan through each section of the documentation without eye-strain. A few good examples (aka my favorites) are documentation for Bootstrap and WordPress‘ “First Steps With WordPress”.

It Helps Other Developers Too

Each developer will have their own coding style. But, when it comes to working in a team, we will often have to share codes with the other team mates. So it is essential to have a consensus on a standard to keep everyone on the same page. A properly written documentation would be the reference the team needs

But unlike end-user documentation, this documentation typically describes technical procedures like code-naming convention, showing how particular pages should be constructed, and how the API works along with the code examples. Often we would also have to write the documentation inline with the code (known as the comments) to describe what the code is doing.

In addition, in the case where you have new members joining your team later, this documentation could be a time effective way to train them, so you don’t have to give them a 1-on-1 run down on the code.

Read Also: 10 Programming Habits Developers Should Adopt

Strangely It Also Helps The Coder

The funny thing about coding is that sometimes even the developers themselves do not comprehend the code that they have written. This is particularly true in cases where the codes have been left untouched for months or even years.

A sudden need to revisit the codes for one reason or another would leave one wondering what was going on in their minds when they wrote these codes. Don’t be surprised: I’ve been in this situation before. This is precisely when I wished I had documented my code properly.

By documenting your codes, you will be able to get to the bottom of your codes quickly and without frustration, saving you a lot of your time that can be spent on getting the changes in.

What Makes For Good Documentation?

There are several factors that to build a good piece of documentation.

1. Never Assume

Don’t assume that your users know what you know as well as what they want to know. It is always better to start from the very beginning regardless of the users’ proficiency level.

If you built a jQuery plugin, for example, you may take inspiration from SlickJS‘s documentation. It shows how to structure the HTML, where to put the CSS and the JavaScript, how to initialize the jQuery plugin at its most basic level, and even shows the complete final markup after adding all these stuff, which is something obvious.

The bottom line is the documentation is written with the thought process of a user, not a developer. Approaching your own documentation this way will give you a better perspective in organizing your own piece.

2. Follow The Standard

In adding documentation that goes inline with the code, use the standard expected of the language. It is always a good idea to describe each function, the variables, as well as the value returned by the function. Here is an example of good inline documentation for PHP.

 /** * Adds custom classes to the array of body classes. * * @param array $classes Classes for the body element. * @return array */ function body_classes( $classes ) { // Adds a class of group-blog to blogs with more than 1 published author. if ( is_multi_author() ) { $classes[] = 'group-blog'; } return $classes; } add_filter( 'body_class', 'body_classes' ); 

The following are a few reference for formatting inline documentation with best practices in PHP, JavaScript and CSS:

• PHP: PHP Documentation Standard for WordPress
• JavaScript: UseJSDoc
• CSS: CSSDoc

If you are using SublimeText I would suggest to install DocBlockr that will cleverly pre-populate your code with inline documentation.

Read Also: Coding Standards For WordPress [Guide]

3. Graphical elements

Use graphical elements, they speak better than text. These media come in useful, particularly if you build software with graphical interface. You can add pointing elements like arrows, circle, or anything that may help users to figure out where to go to accomplish the steps, without guesswork.

The following is an example from the Tower app where you can draw inspiration from. They efficiently explain what how version control works in a pleasing way that makes it more understandable than using plain text command lines.

4. Sectioning

You may consider wrapping a few things in the documentation within bulleted lists and tables as this makes longer content easier to scan and read for users.

Add a table of content and split the documentation in easily digestible sections, yet keeping each section relevant with what comes next. Keep it short and straightforward. Below is an example of nicely organized documentation in Facebook. The table of contents takes us where we want to jump to in a click.

5. Revise and Update

Lastly, review the documentation for mistakes and revise when necessary or and whenever there are significant changes to the product, software, or library. Your documentation would be of no use to anyone if not regularly updated alongside your product.

IMAGE: Wikipedia

Here are some key takeaways from The Art of War that you can apply in your personal life, work, and your quest for self-improvement.

Life And The Art Of War

“Attack is the secret of defense; defense is the planning of an attack.”

Web designers and developers are easily replaceable. Every day there are thousands of new people entering the industry, some are self-taught and some trained in schools. The competition is growing bigger and the only way to ensure success is to constantly build up your arsenal of skills. Never stop learning.

“He will win who knows when to fight and when not to fight.”

In our work, there are a lot of instances when clients would ask for several revisions, tweaks, and minor requests that just pile up and take away days to weeks of our time. And in our line of work, every second truly counts. Learning how to say no, or at least how to renegotiate the details, will come a long way.

Other times several projects will present themselves and you will have to make the hard decision to choose which one to accept, or risk burning yourself, which is harder. This is also a good way of saying that you need to balance your work life and personal life. Is it really a victory that you completed several projects in a week if you missed your sister’s wedding?

“One may know how to conquer without being able to do it.”

Of all the things you want to do in your life, you will only accomplish a fraction of it because of how limited and fast time flows. The cool thing about this all? You can actually “experience” something even without doing it. Or better yet, in order to have more time for yourself, why not outsource some of the things you are doing to someone else? Bring in extra brains and arms to work on the things that are taking way too much of your time.

Read Also: 8 Things You Need To Know About Hiring Freelance Contractors

“Anger may in time change to gladness; vexation may be succeeded by content. But a kingdom that has once been destroyed can never come again into being; nor can the dead ever be brought back to life.”

For practically anyone, every action counts. It’s important to be careful, to think twice, and to plan carefully. Even the smallest mistake could prove costly, and what you may lose might be something you could never get back.

This is a good way of saying never burn bridges, both in your personal and professional life. Particularly with web designers and developers who mostly thrive through their clients. It doesn’t matter if you had a hard time dealing with a specific client, try not to lose contact with them. Who knows, maybe your calm interaction with them even when they were totally aggressive can go a long way into the future.

Read Also:How To Create Your Ideal Client Profiles

“Ponder and deliberate before you make a move.”

Careful planning and precise execution go hand in hand ; it’s no wonder that these two are the integral components of any project’s success. Before making any kind of decision, consider the pros and cons, as well as the consequences that each possible decision could bring forth.

Take this piece of advice together with the third point and you’ll be able to tread life more carefully. This is particularly helpful when dealing with people around you. Another version of this is, “think before you speak” or “measure twice, cut once.”

IMAGE: Pixabay

Work and The Art of War

“Let your plans be dark and impenetrable as night, and When you move, fall like a thunderbolt.”

Make sure to devote a significant amount of time to planning for any project. The importance of a sound plan cannot be overstated; however, without solid action, a plan is just a plan, and nothing more. Many beginners and experts alike fall prey into being overly excited or prideful when working on a project that they fail to fool-proof it, and ultimately leading to a project roadblock. Others call this “overestimating yourself”.

“He will win who knows how to handle both superior and Inferior forces.”

This particular quote is of great significance to team leaders. A web design and development team doesn’t need to have all the advantages just to ensure success. Learn how to manage people, set expectations, and more importantly, develop skill sets.

A balance of proper training, initiative, and cooperation will take your team places – you don’t need to be a multi-billion dollar team of experts to come up with a quality website or award-winning design. Remember, it’s not how you start, it’s how you end.

“There are not more than five primary colours, yet in combination they produce more hues than can ever been seen.”

It’s not in the quantity of tools you have; it’s in how you use them. This quote, which curiously has “design” written all over it, should remind web developers and designers that what truly matters is learning to work with what you have.

Apart from learning how to use your tools properly, you also need to learn to manage risks. Don’t be afraid to try new and unfamiliar things. No one could have known that blue and red make violet, or that mixing red and yellow would result in orange, if no one tried mixing the colors. who knows, a brighter future might be waiting for you, situated where you can’t see it by if you stayed in the same place.

IMAGE: Pixabay

“Move not unless you see an advantage; use not your troops unless there is something to be gained; fight not unless the position is critical.”

Learn to spot opportunities as they arrive; these may be in the form of a new idea for process improvement, catching the attention of a potential big client, or even going to drastic measures such as quitting your day job in order to start your own web design and development firm.

The point here is to always aim high and play to win. Capitalize on every opportunity to get ahead, as long as it doesn’t involve stepping on other people. Think about it. People who have succeeded much in life fought and pushed hard when they saw the opportunity.

“If he sends reinforcements everywhere, he will everywhere be weak.”

Focus is important in order to succeed. Concentrate on key areas of improvement, and don’t try to be everything and anything at once. It is not reasonable to expect designers to be content writing experts, for example, or web developers to be social media strategists.

This is another mistake many of us commit. We tend to think of ourselves as experts in many fields, and in some instances it may be true, but there is only so much we can do with our limited time. Furthermore, it is also proven that spreading yourself across many things, aka multitasking, is bad for your well-being and career.

Personal Improvement and The Art of War

“If you know the enemy and know yourself, you need not fear the result of a hundred battles. If you know yourself but not the enemy, for every victory gained you will also suffer a defeat. If you know neither the enemy nor yourself, you will succumb in every battle.”

As is in everything in life, it is important to have a good understanding of everything. Knowing yourself, how you react to certain things, will go a long way. Especially as a web designer or developer, dealing with clients every day is unavoidable. Knowing their personality will save you from so much trouble.

For example, during my early days as a web developer, I failed to realize that my client then didn’t have an understanding of how websites worked, and I loaded him with details about hosting, FTP, cPanel, and the programming languages and CMS I use. Safe to say, I didn’t become his favorite.

“Victorious warriors win first and then go to war, while Defeated warriors go to war first and then seek to win”

Whether it’s for work or for personal satisfaction, jump in because of passion and because you want to do something, not because you’re expecting some form of compensation or glory at the end. While it’s true that every journey has a destination, you’ll quickly find that there is more to be gained along the way than at the end.

Keep in mind that true victory lies in making decisions that you feel no regret for. If you pursued something that ultimately did not succeed the way you wanted it to, it still counts as a victory, for the sole reason that you put hard work into it and received valuable lessons in return.

“There is no instance of a nation benefiting from Prolonged warfare.”

Strike efficiently, and strike quickly. If you have ideas for self-improvement or projects that you truly believe in, don’t act tomorrow or next week. Act now. This is more important for freelancers. Clients won’t wait for you, you need to catch up with them. The same is true for your dreams. Why delay the implementation of your awesome idea? If you wait long enough, someone else with the same idea will build it.

“In the midst of chaos, there is also opportunity.”

I am talking about learning from mistakes and chaos. No one has reached a great deal of success without experiencing their fair share of problems. We learn how to properly align our div tags using CSS the hard way. Nine out of ten web designers and developers I know never quite figured out how to align divs side by side until after several hours later.

Read Also:6 CSS Tricks To Align Content Vertically

There is always a lesson to be learned in the midst of chaos. It may be difficult to deal with now, but if you push yourself to fix the issue, you won’t have to deal with it again in the future.

“Never venture, never win!”

For everyday people like you and me, a career change can go a long way. In fact, right now, there are a lot of people founding their own startups. This rings particularly true for me. I left my job of 4 years several months ago in order to freelance full-time, which was the second best decision I made.

The best decision I made is partnering up with a web design company. It’s a pretty big leap, but hey, “Never venture, never win!” Be it a new skill, new project, or new career you are thinking of, if it makes you lose sleep at night and makes you all excited in the morning, you might want to consider pursuing it!

IMAGE: Pixabay

Final Words

Here’s one more passage from The Art of War for everyone to remember: “If you know the enemy and know yourself, your victory will not stand in doubt; if you know Heaven and know Earth, you may make your victory complete.” Overall, what The Art of War tells us is that we need to be aware of ourselves and of others. By keeping an open mind to the things that are happening around us, we can make informed decision that will not only help us in our personal lives, but also at work.

Now Read:

How To Become A High-Demand Designer

2. Headslinger

Use it to: Find news that’s relevant to you faster than ever before.

Need a way to quickly browse through news headlines? Give Headslinger a shot. With Headslinger, you can follow the most popular publications on the Internet categorized under different sections such as arts, auto, tech, food, travel, health, humor, entertainment, and more.

You can sort your news sources and keep them in separate folders for better organization. At one glance, you are presented with all the headlines of any publication along with a small excerpt – from here, you can directly share these headlines on your social networks or “sling” them to be read later when you want to.

3. Utopic

Use it to: Easily save web pages with one click and sort them in folders.

Browser bookmark systems are often too basic to serve any real purpose. In most cases, we just click on the bookmark button and then lose track of it; the bookmarks just keep piling on in an endless list that we never end up using. But thankfully, better tools are available.

Utopic is a visual bookmarking tool with social features that lets you find, save, and sort web pages. Setup is really easy, all you need to do is sign up with your Twitter or Facebook account – and once inside, you can either use a bookmarklet or a Chrome extension to create your bookmarks.  If you’re looking for an alternative, check out Diigo.

4. Prismatic

Use it to: Get highly personalized recommendations of what to read next.

Prismatic is a beautifully designed news curation and discovery app that uses machine learning algorithms to filter content that aligns with the interests of a specific user. To start your account, you select and follow ten topics out of the many available such as business, television, health, technology, automotive, DIY, and more.

Once you’ve done that, you’re led to your Prismatic homepage, which presents stories from the topics and the people that you’ve followed. Once you start reading, liking, and sharing stories, Prismatic automatically and continuously serves up content best suited for you.

5. Protopage

Use it to: Set up your go-to page on the internet for information and task management

Protopage is an RSS reader, virtual desktop, and Internet start page. It’s an extremely feature rich tool that allows you to create a completely customize page just for yourself on the Internet. You can use it to read your own selection of blogs and news, create to-do lists, keep bookmarks, place sticky notes, add photos, manage your calendar, and more.

The basic organization on the page is done by creating, editing, and arranging widgets as per your needs. Protopage also optimizes content for viewing on mobile devices such as Android, iOS, and Blackberry.

6. Saved.io

Use it to: Create bookmarks easily without installing any resource-intensive extensions

Saved.io is the simplest bookmarking system that you will ever use. There are a lot of bookmarking tools out there, but almost all of them need you to install some sort of browser extension to work – and of course, if you use different browsers on multiple devices, you’ll need to find and install the right extensions for them all. No need for all that with Saved.io.

All you have to do is create an account and prepend “saved.io/” to any link in your browser and hit enter. That’s it. Your bookmark is now saved. You can create lists if you like, but other features such as tags and descriptions have been eschewed in favor of simplicity. Who’s complaining?

7. Kippt

Use it to: Collect design inspiration, tell stories, research new subjects, and much more

Kippt is a full-feature curation and archival tool that allows you to save links, read articles, watch videos, share notes, and much more. Your collections can be private or public, or shared with the people you work with. Kippt makes your information workflow and archiving effortless.

When you collect something to Kippt, the page and the content will be searchable, organizable, readable on your devices and easily sharable too.

So these were some tools that can help you save time, be more organized, and manage information in a more effortless manner. What are some tools apart from these that you use to curate information?

Editor’s note: This post is written by Vishveshwar Jatain for Hongkiat.com. Vishveshwar, a writer and editor for over 6 years, with experience in both digital and print media, is now a content marketer at AdPushup; which helps users optimize ad revenue generated from their existing ad units. Find him on Twitter.

MagnificPopup

MagnificPopup is another lightbox plugin, developed by the same person that gave us PhotoSwipe, Dmitry Semenov. It comes in the form of a jQuery/Zepto plugin, and also brings capabilities that are missing in PhotoSwipe such as support for Video, Map, and Ajax content. This is a great alternative for those who prefer having more features at hand.

• Dependency: jQuery 1.9.1+, or Zepto.js
• Browser Support: IE7 (partially), IE8+, Chrome, Firefox, Safari, and Opera.
• License: MIT license

SwipeBox

Swipebox is a jQuery plugin with touch gesture support for mobile platform. It also supports videos from Youtube and Vimeo aside from images. Swipebox is also downright easy to implement, and has a handful of options to customize its behavior. I think Swipebox is a great lightbox plugin for JavaScript noobs.

• Dependency: jQuery
• Browser Support: IE9+, Chrome, Safari, Firefox, Opera, IOS4+, Android, and Windows Phone.
• License: Undefined

iLightbox

iLighbox is a jQuery lightbox plugins with a wide range support of media types: including videos, Flash / SWF, Ajax content, iframe and maps. This plugin also adds social media buttons on top of the media, allowing your users to share it to Facebook, Twitter or Reddit. Also check out the advanced section to see how iLightbox can be applied in different scenarios.

• Dependency: jQuery
• Browser Support: IE7+, Chrome, Firefox, Safari, and Opera
• License: Undefined

Lightbox for Bootstrap

Lightbox is one of the glaringly missing pieces from Bootstrap. This plugin fixes that. If you are using Bootstrap, I highly recommend using this library. The plugin is well-integrated with Bootstrap’s code-base.

• Dependency: jQuery and Bootstrap Modal
• Browser Support: IE8+, Chrome, Firefox, Safari, and Opera
• License: GNU license

Nivo Lightbox

Nivo Lightbox is a flexible lightbox plugin. Several options are included to change the appearance into the way you like it to appear, such as changing the theme, the transition effect, and switching the navigation.

• Dependency: jQuery
• Browser Support: IE9+, Chrome, Firefox, Safari, and Opera
• License: MIT license

ImageLightbox

ImageLightbox is a lightbox plugin without the bloat. It is built specially for image hence the name given — no video or other media type supported. It also does not require extraneous HTML markup; the <img> element is sufficient. The plugin just works.

• Dependency: jQuery
• Browser Support: IE9+, Chrome, Firefox, Safari, and Opera
• License: Undefined

Mini Lightbox

Another lightbox plugin with none of the bloat. The library is only 2kb, and works only with images. It’s the perfect plugin if you only designate for the latest browser and do not need to overlay other media types like videos.

• Dependency: None
• Browser Support: IE10+, Chrome, Firefox, Safari, and Opera
• License: MIT license

LightCase

Lightcase is a lovely lightbox plugin. It comes with several animations that makes user interaction come alive, like fade, elastic zoom and scrolling. Furthermore, it also supports various types of media including Youtube embed, HTML videos, SWF and input forms. The plugin also properly handles media cannot be reached or found errors

• Dependency: jQuery
• Browser Support: IE9+, Chrome, Firefox, Safari, and Opera
• License: GPL license

Yalb

Yalb stands for Yet Another Lightbox — but it’s not. Yalb comes with a handful of APIs including custom events that allow you to identify lightbox states, such as when it is open and when it is close. Yalb comes in two version, Vanilla JavaScript and jQuery plugin.

• Dependency: None
• Browser Support: IE9+, Chrome, Firefox, Safari, and Opera
• License: MIT license

FeatherLight

The 6kb Featherlight is a bare plugin for savvy developer and carries only the essentials. If you need, for example, to group image lightbox in a gallery, you can include the gallery extension. You can also develop your own extension for this plugin to fit in your project needs.

• Dependency: jQuery
• Browser Support: IE8+, Chrome, Firefox, Safari, and Opera
• License: MIT license

LightLayer

LightLayer is an easy to use lightbox plugin. It has a handful of options, custom JavaScript methods, and custom events. the plugin works with images, videos, maps, and external content. What’s more can we ask.

• Dependency: jQuery
• Browser Support: IE9+, Chrome, Firefox, Safari, and Opera
• License: MIT license

LightGallery

LightGallery, another lightbox plugin with a lot of features added. It comes with more than 20 options to customize the tiniest of details of the lightbox.

• Dependency: jQuery
• Browser Support: IE7+, Chrome, Firefox, Safari, Opera, iOS, Android, and Windows Phone
• License: MIT license

FluidBox

Fluidbox is an image lightbox plugin that is inspired from Medium. It works with images under various circumstances including floating image, image with absolute position, images that have border and padding, and galleries. Check out how it was built. If you need a WordPress plugin, there is one.

• Dependency: jQuery
• Browser Support: IE9+, Chrome, Firefox, Safari, Opera
• License: MIT license

StripJS

StripJS is a unique lightbox plugin. Rather than overlaying the image, the plugin slides the images in from the side instead, so that it won’t block the whole content. StripJS supports both image and video.

• Dependency: jQuery
• Browser Support: IE7+, Chrome, Firefox, Safari, Opera, iOS 5+, and Android 3+
• License: Creative Commons BY-NC-ND 3.0 license

2. PicsArt

PicsArt is a powerful collage maker, which offers three modes to create photo collages: Grid, Frame and Background. All three modes offer different sets of collage templates. Frame provides lots of collage templates like birthday, nature, travel, etc. It lets you add photos from various services other than your computer’s local storage, such as PicsArt network, Flickr, Instagram, Facebook, Picasa, etc.

3. Fotor

Fotor is a photo editor for multiple platforms including the web but is also a great photo collage maker. You can customize the border, background, template and photo quality. Pick your photo collage using any of the three offered modes: Template, Freestyle and Photo Stitching or go with the Freestyle mode, which allows you to organize the photos in any form or style of your choice. Check out our in-depth review on it.

4. Phototastic

Want to make a photo collage for a lot of photos? Phototastic lets you group up to 25 photos in the same collage. Fetch your photos from local storage, straight from your camera, or from Flickr then use their grid templates to create your collage. On top of that, you can customize the border, photo shape, frame, background, or add text or stickers to the photo collage.

5. Atlantas

Atlantas provides two layouts to start with the photo collage: Smart layout and Advanced layout. The simple Smart layout offers fewer customization options (only border and layout options) and a grid-based result. The Advanced layout offers freestyle placement of images along with more customization option, such as shapes, templates, background, photo shape, photo groups, etc.

Cool Collage

Want to keep it simple? Cool Collage keeps things basic and simple, just add the photos, choose a background and photo size, adjust or arrange the photos, and it’s complete. It offers a freestyle collage template, wherein you can place the photos in any form or style of your choice. You can also share your collages with your friends and family via Facebook or the Charms Bar in Windows 8.

My Collage

My Collage not only lets you create photo collages but also customized e-cards for various occasions. Choose one of the many given collage templates, add your photos and that’s it, you’re done.

While there are few customizations, you can add text, which can be used to write custom greetings or quotes on the photo collage or e-card and make them more personal. Share your masterpiece on Facebook.

Photo Joiner

Photo Joiner cannot be any simpler. Creating a photo collage using this application is as simple as choosing the photos and setting some customization options. It simply joins the photos in a vertical or horizontal grid to make a photo collage.

It offers only the basic configuration options, and no fancy or advance options such as collage templates, text, stickers, etc. are provided as its competitors. It also allows to share your collage on Facebook and Twitter.

Tap Collage

Tap Collage is a simple collage maker, which is not only limited to photo collages but also offers to create e-cards. You’re limited to pre-defined templates for making collages as well as e-cards using this application.

There are templates for creating collages of various types and e-cards for special occasions. The only option it offers is background color and this make the whole process easy: you only need to choose the template and add the photos, and the collage or e-card is ready!

Bonus: Pic Stitch (Paid)

Pic Stitch, as the name suggests, lets you stitch pictures, i.e., join photos to create collages. It’s a premium application that comes at a small price for Windows platform.

Some of the offered features are stickers, photo effects, rich collection of collage templates, and various customization options such as texture and border layouts, photo aspect ratios, etc. You can also share your masterpiece on social networks like Facebook, Twitter and Instagram.

[Download]

Now Read:

20 Useful Microsoft Windows 8.1 Tips & Tricks