Code Better with Froala’s Enhanced Documentation

We’ve recently refreshed the Froala docs to provide you a better reading experience. The documentation pages should now be able to give you the information you need faster with various improvements in page design, wordings, and examples/step-by-step guides.  In this blog post, we’ll show you how Froala’s latest docs refresh makes concepts easier to follow. Along the way, we’ll also discuss the reasons why good documentation can make good code. 

Introduction

It is important to keep records. Almost every programmer who has written code for a program has read some kind of documentation. Documentation is used every day, whether it’s a tutorial page for people learning a programming language, an API reference with useful events, or a guide that people can follow. Users of a piece of software would not know what to do without documentation. They would have to learn and train by doing things by hand. Because of this, most applications, APIs, and languages today make their documentation easy for everyone to find and use. Documentation saves both users and providers a lot of time and money.

Why do we need to keep documentation up-to-date and make it better?

It isn’t enough to have “acceptable” documentation in place and leave it alone for years. People who want to give their users a documentation page should keep it up to date and look for ways to make it better. This is because out-of-date, unclear, or wrong documentation could make it harder for users to learn. Imagine reading through documentation that was put together quickly and has grammatical or, even worse, code syntax mistakes, bad navigation, and missing or wrong information. That would be very frustrating for users, who might think they are doing everything right but still can’t get what they want. What will happen if that does happen? Back to support tickets, which can take a lot of time for everyone.

Why does good documentation lead to good code?

As developers, we need to ensure that our codes should ultimately be of good quality. This practice leads to easier code refactoring, faster debugging, faster performance, better readability, and reusability. In short, it makes the development cycle a lot easier. But did you know that documentation actually has an impact on code quality? This is what we’ll explore in this section. 

Based on what we’ve said about how documentation directly affects the quality of code, poor documentation should also affect the quality of code. For example, leaving out best practices or leaving out details could lead to code that is messy and hard to keep up with. This makes it very hard to refactor or release new versions of an application, an API, or a language. This could also cause a number of errors in the code, some of which could happen when the program is running.

Also, documentation with incomplete examples (like only explaining the basic use case) could make users get stuck and not be able to use the software’s features to their full potential. This forces them to deal with most of their problems on their own. And when any of the above happens, it will be too late, and users will wish they hadn’t followed the badly written instructions.

A Developer’s Best Friend

On the other hand, good code can come from good documentation. A developer’s best friend can be a well-made docs page that is updated often, easy to navigate, complete but simple, and full of complete information and examples. It can cut down on the number of times a developer needs to call for help or browse the internet because everything they need can be found there quickly. Developers can write better code with the help of good documentation because:

• It doesn’t leave much room for doubt. – By being straightforward and clear, a documentation page lets readers learn and work right away without thinking whether they’re on the right track or not. For example, let’s say that a docs page gives users plenty of ways to accomplish a task (e.g., installation, adding images, etc.). Users should be able to easily differentiate between these methods and determine which are appropriate for their case. 
• It makes less mistakes – Documentation should have as few mistakes as possible, whether they are grammatical or with the way the sentences are put together. Grammar mistakes, typos, and duplicate content could slow readers down in the same way that missing content could. On the other hand, users could copy mistakes from code examples into their own code.
• It lets programmers write code more quickly. – Learners can find what they want quickly and easily on a Docs page that has a search bar and is well-designed for page navigation. So, developers can spend less time writing code.
• It lets first time learners progress naturally – Isn’t it annoying when you visit a documentation page for the first time only to find scattered, unstructured information? A good documentation provides a “path” for beginners to follow, starting from high-level information and narrowing down to specific information, references, and examples. 
• It makes it easier to take care of. – Documentation makes code easier to maintain by telling people about best practices, content that has been removed or will be removed soon, and important changes. This means that people who read the code will always know what should be kept, changed, and made better.

Froala updates its docs often to make them easier to comprehend and help you produce quality code.

What’s new in the Froala docs? 

The latest revision in the comprehensive documentation of our HTML editor consists of the following improvements:

Adding labels and information that will help

The latest Froala docs now have additional helpful information, including labels for steps and “What’s Next” sections on some pages. 

Rephrasing vague wordings

Some phrases, sentences, and labels have been improved to be clearer. This helps readers understand concepts more easily. 

Enhancing navigation

How the Froala docs get around has changed a lot. The navigation menu on the page is now better organized, going from big to small ideas. The first steps, tips for getting to know the site, and most important examples are now closer to the top of the menu. The changelog, migration guidelines, and other less-used pages have been moved to the end of the menu.

Froala docs’ WYSIWYG Editor SDKs page is another great example of excellent navigation in documentation. It contains the various SDKs in which Froala can be integrated in the form of button icons. By clicking on them, a user will be taken to the specific Server SDK page. Users can get to the SDK page using the left menu. Users can choose the easier option.

Making titles more consistent

Some titles in the Froala docs have now been made more consistent with one another, contributing to the docs’ readability. They have similar structures (verb + subject on all titles) and lengths. In the graphic above, steps 1 through 3 have similar titles but different meanings.

Beautifying the search bar

A search bar is an important part of any docs. It makes it easy for people to find the information or content they need without having to look through dozens of pages. The search bar on Froala docs has been moved to a more standard place, making it look better and be easier to use.

Making the navigation menu items easier to understand

We’ve moved the navigation menu items around and made them easier to understand. They are now easier to click on and use carets and the right amount of indentation to show which subject or idea is now expanded.

Getting the layout right

Lastly, the layout has a big impact on how easy it is for people to understand the information. A messy design can make it hard for people to read, while a clean, well-organized one makes it easier. Froala has made sure that its responsive layout has enough space for people to read.

We Take It Seriously

Froala takes documentation seriously. We want you to understand Froala and use it to its fullest to improve your app and make sure your users are happy. Because of this, we keep adding to and improving our documentation page. Rest assured that we will keep optimizing, rewriting, and adding new, helpful content in the years to come. You’ll never get lost in paperwork again with Froala. We’ll be there to help you figure things out.

Pricing is another important thing to Froala, just like documentation. We want developers to get as much as possible out of the editor they choose. That includes the best price-to-quality ratio. Some editors charge extra for crucial features or for loading more than a specific amount of pages. Froala is neither of these. All of our plans, even the free one, have all of Froala’s powerful features. There are no limits on the number of users or uses. Talk about total freedom to change things. Because of this, Froala is a lot cheaper than other editors on the market.

Conclusion

In this blog post, we talked about the update to Froala’s documentation. We also talked about how important good documentation is and how it can help make code better. Documentation should be something that is easy to find and understand. It’s one of the most important parts of making software, and it can have a direct effect on how well a project works and how long it takes to make. The docs page for Froala is a good example of good documentation that is clear, helpful, and easy for developers to understand. And we make it that way because we care about you and what you’ll make.