DEV Community: Joy Ose Akhanolu

How to Write Documentation That Converts

Joy Ose Akhanolu — Wed, 26 Jul 2023 07:42:58 +0000

Documentation is an essential part of any software project. Imagine you're working on a cool tech project, like creating a new app or website. Well, good documentation helps everyone understand what's going on! It helps users understand how to use the software, troubleshoot problems, and learn about its features.

It's like having a secret code that makes everything clear. We want everyone involved to understand what's happening when we work on projects.
However, not all documentation is created equal. Some documentation is clear and easy to understand, while other documentation is so dense and jargon-filled that it's impossible to make sense of.

If you want to write clear and understandable documentation, there are a few things you need to keep in mind. Let's get started!

1. Know your audience.
Just like speaking to different people, writing documentation requires understanding who will be reading it. Who will be using your documentation? What are their needs and expectations? Once you know your audience, you can tailor your documentation to their specific needs.

For example, if you're writing documentation for a technical audience, you can use more technical language. However, if you're writing documentation for a non-technical audience, you'll need to use simpler language and avoid jargon.
Remember: Always keep it SIMPLE!

2. Use clear and concise language.
Clarity is key to effective documentation. Your documentation should be easy to read and understand. Use clear and concise language that is free of jargon. Avoid using technical terms unless they are necessary. Use active voice to make the content more engaging and understandable.

3. Use examples and Use Cases.
Practical examples and use cases can illustrate how to use the software or implement specific features. Real-life scenarios provide context and help readers understand the functionality more effectively. Use a mix of code snippets, illustrations, and step-by-step examples to make the documentation more relatable.
Examples can help users understand your documentation more easily. When you're explaining a concept or procedure, provide examples that illustrate what you're talking about.

4. Use visuals.
Incorporate visual aids, such as diagrams, flowcharts, and screenshots, to complement the textual content. Visuals can effectively convey complex concepts, making the documentation more engaging and accessible. Ensure that the visuals are clear and labeled appropriately to avoid any confusion. Visuals help make your documentation more understandable.

5. Organize your documentation logically.
A well-organized document is easy to navigate and comprehend. Start with an overview or table of contents to provide an outline of the document's structure. Use headings, subheadings, and bullet points to break down complex information into manageable sections and lists to help users navigate your documentation. Logical flow and formatting consistency contribute to the document's overall readability.

6. Proofread your documentation carefully.
Before you publish your documentation, proofread it carefully for grammar, spelling, and punctuation errors.

7. Document APIs and Code.
For technical documentation, thoroughly document APIs and code libraries. Include descriptions of parameters, return values, and usage examples. Use consistent naming conventions and follow industry-standard practices for code formatting to maintain a professional and uniform appearance.

8. Get feedback from others.
Don't be afraid to seek feedback from your team and end-users. Feedback helps you identify areas of improvement and refine your documentation for optimal clarity. Ask them if they understand your documentation and if it is easy to use. This helps you identify if you might have missed out on any helpful information.

9. Keep It Updated.
Documentation should evolve alongside the project. Regularly review and update the content to ensure it reflects the most recent changes and enhancements. Outdated documentation can lead to confusion and errors.

By following these tips, you can write clear and understandable documentation that will help your users get the most out of your software.

Additional Tips:
Use active voice instead of passive voice.
Use simple sentence structures.
Break up long blocks of text with headings, subheadings, and lists.
Use a consistent tone and style throughout your documentation.

By following these tips, you can write clear and understandable documentation that will help your users get the most out of your software. Remember, clear and understandable documentation is the backbone of any software project.

Keep it simple, and do not be afraid of making errors while at it, hence, the room for proofreading and getting feedback.

What happens when you type google.com in your browser and press Enter

Joy Ose Akhanolu — Sat, 08 Oct 2022 08:32:55 +0000

As a beginner, you've probably always wondered how the internet functions whenever you enter a URL. We would examine the infrastructure part of a web and how it functions in this article.

Before I begin, let me clarify three # concepts that will be important throughout this article:

- Servers

A server is a computer program or equipment that offers a service to another computer program and its user, referred to collectively as the client. The physical machine that a server program runs on is sometimes referred to as a server in a data center. That machine could be a dedicated server or it could be utilized for anything else. Servers are frequently classified based on their intended use. The word "server(s)" shall be used in this article to refer to the computer system(s) that host www.google.com.

- Client

A client is a computer or program that, as part of its operation, sends a request to another program, computer hardware, or software that accesses a service provided by a server (which may or may not be located on another computer). Online browsers, for example, are clients that connect to web servers and retrieve web pages for display.

- Protocol

A protocol is a collection of rules or processes used in computer science to convey data between electronic devices such as computers. To transmit information between computers, there must first be an agreement on how the information will be organized and how each side will send and receive it. OSI (Open Systems Interconnection), a collection of standards for implementing networking communications between computers, is the most essential computer protocol. TCP/IP (Transmission Control Protocol/Internet Protocol), HTTPS (Secure HyperText Transmission Protocol), SMTP (Simple Mail Transfer Protocol), and DNS are some of the most essential Internet protocols (Domain Name System).

Additional technical terms that will be utilized in this article:

DNS Request
FireWall
HTTPS/SSL
Load Balancer
Web / Application Server
Database Server
Google Server
TLS
Internet

DNS Request

A DNS query, often referred to as a DNS request, is a request for data sent from a user's computer to a DNS server by a DNS client. A DNS request is often performed to obtain the IP address linked to a domain name.

FireWall

A firewall is a network security device that monitors and filters incoming and outgoing network traffic depending on previously set security policies in an organization. Firewalls protect traffic at a computer's entrance point, known as ports, where data is exchanged with external devices.

HTTPS / SSL

The standard technology for keeping an internet connection secure and protecting any sensitive data that is being sent between two systems is called SSL, or Secure Sockets Layer. This technology stops criminals from reading and altering any information transferred, including potentially personal details. When a website is protected by an SSL certificate, HTTPS (Hyper Text Transfer Protocol Secure) is displayed in the URL. By clicking on the lock icon on the browser bar, you can read the certificate's details, including the issuing authority and the corporate name of the website owner.

Load Balancer

Load balancing, commonly referred to as server farming or server pools, is the process of efficiently dispersing incoming network traffic among a collection of backend servers. The sole point of contact for clients is a load balancer.

Web / Application Server

A web server accepts and processes client requests for static material (such as HTML pages, files, pictures, and videos) from a website. A software framework that transforms data to provide the particular functionality provided by a business, service, or application is known as an application server. Application servers improve the interactive sections of a website, which might change depending on the context of the request.

Database Server

Any server that runs a network database program and manages database files, such as Microsoft SQL Server or Oracle, is referred to as a database server. SQL Server is a powerful database management solution.

Google Server

Google Web Server (GWS) is the proprietary web server software used by Google for its web infrastructure.

TLS

Transport Layer Security (TLS) is a cryptographic technology developed to offer network communications security.

Internet

Internet is a worldwide computer network that provides a variety of information and communication services and is made up of interconnected networks that use standardized communication protocols

Now that we've defined these terms, what happens when you type google.com into your browser and hit Enter?

To get the IP address for google.com, the browser searches its cache for a DNS record

Your browser needs to determine which Internet server to connect to when you type the URL into it and hit Enter. In order to accomplish that, it must see the DNS server on your corporate network or at your ISP, it does a recursive DNS lookup if the browser is unable to locate the IP address at any of those cache layers. Recursive DNS lookups search through several DNS servers on the Internet, which then query other DNS servers until the desired DNS record is located.

The browser must now locate the server on the Internet and create a connection after receiving the DNS record with the IP address of the server that is home to the website you entered. Between your browser and numerous locations around the Internet, there are various layers where DNS data is cached. Your browser checks its cache, the operating system cache, a local network cache at your router, and a DNS server cache on your company's network or at your ISP (ISP). If the browser is unable to locate the IP address at any of those cache layers, your ISP's or corporate network's DNS server performs a recursive DNS lookup.

The browser will then establish a TCP connection with the server.

The browser connects to the server using TCP after acquiring the IP address. Packets from a client browser request are routed through the router, the ISP, and an internet exchange to transfer ISPs or networks, all while utilizing transmission control protocol (TCP) to discover the server with the IP address to connect to at port 443. After the browser connects to the server, a Secure Socket Layer (SSL) certificate is generated to indicate that the domain is secure. The next step is to make an HTTP request to obtain the resource or page.

HTTP requests are sent to the server by the browser.

Now that the browser is connected to the server, it follows the HTTP(s) protocol's communication rules. It begins with the browser sending an HTTP request to the server in order to obtain the page's contents. The HTTP request includes a request line, headers (or request metadata), and a content. The request line provides information that the server can utilize to determine what the client (your browser in this example) wants to perform. Google.com gets the request, utilizes the passed information (cookies) to determine who the user is, location, language, and region, and sends http redirects (HTTP GET 302) to the browser to use the local regional Google server, i.e. google.com. in this case.

Client receives response from server after processing request.

The server accepts the request and determines how to handle it depending on the data in the request line, headers, and body. The requested content is retrieved from the accessible database.

The following is included in the answer:

A status line that informs the client of the request-response status and response headers that instruct the browser how to treat the response to the resource being requested at that path, which may be content like HTML, CSS, Javascript, or picture files, or data.
Static files, both text (HTML files) and non-text data, are examples of resources (images). But static files aren't usually requested by browsers. There is frequently no file attached to these resources because they are frequently dynamic resources created at the moment of the request. After then, the content is rendered by the browser.

The manner in which the browser renders content

The browser layout engine will begin to construct the final page for display. CSS and JS information may change the page's layout. When the browser receives the server's answer, it examines the response headers for information on how to present the resource. The Content-Type header above informs the browser that an HTML resource was received in the response body.

There is sometimes a high volume of client queries to servers (you are typing google.com, other people are typing so much more). A load balancer is used to improve server efficiency and reduce loading time. The final page is put together and displayed to the user. Following that, the browser may send more AJAX requests to connect with the web server even after the page has been rendered.

Conclusion

Although this appears to be a long and tiresome procedure, we know that a web page renders in less than a second after we push enter on our keyboard. All of these phases occur in milliseconds before we are even aware of them. That is the power of the internet.

Thank you for reading!