Programming Best Practices for Technical Writers – Encapsulation

This post marks the beginning of a series aimed at exploring essential programming best practices for technical writers, starting with the concept of encapsulation.

Encapsulation involves hiding the internal workings of a system or component and exposing only necessary interfaces. For technical writers, this means being able to clearly document how users should interact with a system without needing to delve into or explain its internal complexities. It helps in creating user guides and API documentation that focus on what users need to know, without overwhelming them with details.

Consider the example where a constructor initializes an object’s state with properties such as make, model, and year. Two methods, displayDetails() and drive(), are used to show the car’s information and simulate driving, respectively. An instance of the Car class is created with the new keyword, and these methods are invoked to interact with the object.

This programming only exposes the methods that are essential for the object’s interaction with other parts of the code. This reduces the chance of unintended interference with the object’s state.

Additionally, access modifiers like private and protected enable developers to restrict access to an object’s internal state. Public methods on the other hand are accessible from outside the class and allow external code or other objects to interact with the internal state or perform actions using the object.

Encapsulation is a key principle of object-oriented programming (OOP) that bundles data and methods within a class, often restricting outside access. By understanding encapsulation, technical writers can clearly explain this concept, especially when documenting APIs, libraries, or frameworks. This knowledge helps writers organize documentation around the public interfaces, allowing users to focus on how to interact with the software without being overwhelmed by its internal details.

Those are the basics of encapsulation. The next post goes over inheritance.