The document discusses how principles of object-oriented programming (OOP) such as abstraction, encapsulation, inheritance, and information hiding can be applied to writing technical documentation topics. These principles aim to reduce complexity, improve handling of complexity, and facilitate change management by categorizing topics as generic, specific, or complex depending on their level of detail and potential for reuse. The document provides examples of how OOP concepts like classes, objects, and inheritance relate to DITA topics and recommends technical writers and information architects reassess their documentation modularization strategies based on these OOP design patterns.

1. Do You Think OOP
(Object-Oriented Programming)
When Writing Topics?
by Gunnar H. Krause

2. Why do we talk about Programming?
HTML
D I T A
DOCBOOK
XML
OOP
Minimalism
other
Authoring
Best Practice

3. Outline
n What is OOP, non-OOP and Oops?
n Bridge to DITA specification
n Writing topics with OOP in mind
n Generic, specific and complex topics
n Thoughts to take away

4. Object-Oriented Programming
n OOP is a programming paradigm using "objects"
to design applications and computer programs.
n An object can represent any useful item that has
n identity, structure, behavior.
n An object is a data structure consisting of
n data fields, methods together with their interactions.
n OOP basics are rather old.
n OOP got a hype in 1990s.
n OOP is regarded state-of-the-art today.

5. What about Non-OOP?!
n Example: procedural programming
n Software code consists of procedures and call of
procedures.
n Procedures define variables and parameters to process
information and compute results.
n Reuse is possible on procedure level from basic
functions to complex processing.
n Many other ways of non-OOP are possible.

6. Oops !!!
n Many programming languages support
object orientation.
n But, you are never forced to good OOP.
Knowing the DITA specification or
using a DITA-based authoring system
does not enforce user-friendly and easy
to maintain documentation, either.

7. What to Learn?
n Understanding the basic principles is needed.
n Experience is needed as well.

8. What is an Object in OOP?
n An object is something with
n a unique name
n properties
n methods that can be performed with it
n My car
n Registration plate number M-GK1
n Driver window 75% open, engine stopped
n Ability to close a window, start engine
Name
Property_A
Property_B
Method_1()
Method_2()
M-GK1
WindowLeft
Engine
WindUp()
Start()

9. Abstraction
n Ignore unimportant details for a certain level of
aggregation
n A combination of stone, wood,
glass can be described as a house
n A collection of houses is a town
n Abstraction reduces complexity by separating
levels of detail.
n You can still reach the other level of detail by
intentionally looking at a related object.

10. Encapsulation
n Encapsulation is an imperative
n to keep things together that
belong together,
n on the same level of abstraction,
of course.
n Do not split things that belong together.
n Complexity is reduced by collecting relevant
information in one place.

11. Inheritance
by Specialization D Generalization
n On one level of abstraction you may find similar
objects.
n Define a superclass
with what is common.
n Derive more specific
classes based on this
one.
n Redefine properties
or methods
n Add properties
or methods
Convertible
Roof
OpenRoof()
eCar
BatteryLevel
{FuelLevel}
LoadBattery()
{FillTank()}
Car
FuelLevel
Engine
FillTank()
Start()

12. Inheritance (2)
n A link between two specific classes is established.
n You can easily detect commonalities versus
specific characteristics.
n Inherited associations
n My_eCar can drive on the same road as MyConvertible.
n A driver can use My_eCar or MyConvertible.
n General methods reduce complexity as you do not
invent the wheel twice.
n Generalization and specialization are two
approaches that lead to the same class hierarchy.

13. Information Hiding
n Hiding secrets should apply for
n any difficult design decisions or
n design decisions which are likely
to change.
n Provide methods for everything that can be done
with the object independent of the current
internal implementation.
n Complexity is reduced for the case of changing
the internal solution.

14. What is a Class in OOP?
n Every object belongs to a class.
n A class is a static description.
n An object is a dynamic instance.
n All properties and methods of an object are
defined in its class.
n The class is therefore a virtual thing.

15. Bridge to DITA Specification

16. Bridge to DITA Specification
n The generic DITA topic is a class.
n Its DTD describes the possible properties.
n A topic titled “Your New Family Van" based on this
DTD is an object.
n A task topic is a subclass.
n Its DTD enables more specific topics like "Closing the
driver window" (object).
Note: In DITA, the term “topic” is used for
the class (“we write reference topics”) and
the object (“my map references 21 topics”).

17. Bridge to DITA Specification
n Class methods are handled by the open toolkit
n Resolving conref information
n Creating links between topics
n Formatting title and using it as link text
n Embedding images
n It is defined once how something like a <title>
behaves in an html or PDF context.

18. Applying Lessons Learned from OOP
n Is your technical documentation about complex
products that may change faster than before due
to shorter design cycles?
è Reduce complexity
è Improve handling of complexity
n Do your engineers prepare, provide, or support
the product documentation?
n R&D engineers may already know OOP.
n You can speak their language.
è Facilitate change management

19. Writing Topics for Products or Services
n The class is a product family the company offers.
n DDR3 memory module
n The subclass is the specific product or service you
can order from the company.
n 2 GByte PC3-6400 Unbuffered DIMM
n The object is the specific thing bought or used by
the reader of a technical document.
n Example: identify object by serial number

20. Writing Generic Topics
n Details have to be described on the right level of
abstraction in a hierarchy of product classes.
n “Feature List” are reference topics with title and
metadata according to the level of detail.
n Features of
n a DRAM,
n a DDR3 DRAM,
n a 70 nm DRAM technology
n a specific 1Gbit DDR3 DRAM project in 70 nm

21. Mindset Problems
n This approach was introduced to internal technical
documentation in R&D.
n Traditionally the complete list was authored and
sorted on project level.
n The new approach splits a list “artificially” into
sub-lists.
n “We are not used to this.”
n “We do not need this inside this project.”

22. Improvements
n Happy readers
n Some users need to know the
commonalities to reuse test
equipment or packaging.
n Others are interested in the differences to cover the
special features in new test routines.
n Program manager can readily identify reuse
opportunities as well as issues driven by changes.

23. Topic Categories Introduced by Gunnar
n New metadata to handle topics in CMS
n Generic (topic)
n Content is applicable to a range of projects
n Information is unlike to change and ready for reuse
n Specific (topic)
n Content is specific to a project
n No reuse, no dependencies
n Complex (topic)
n For the sake of encapsulation some topics are
better off with conditional text to handle
project specific information.

24. Rendition
n For internal publishing
n Keep separate lists or concepts to emphasize what is
common or specific across products
n Filter complex topics to fit product
n For external publishing
n Merge lists and concepts for integrated text flow
n Filter complex topics for external readers

25. Information Hiding in Authoring
n With the concept of “Information Hiding” writers
have been convinced that
n users do not need all the information in one spot,
n fewer text updates are needed when revising the
implementation.
n This is part of the approach called “minimalism”.

26. Information Hiding in Authoring
n Separate information according to reliability
n Stable or approved information
Features of DDRx Standard – Consensus List
• Supply Voltage of 1.2 V
• FBGA Package
n Transient or preliminary information
Potential Features of DDRx Standard
• Low density components: 512 Mbit and 1 Gbit
• Burst chop mode
n Separate topics reduce scope of change.
n Unreliable topics can be marked or excluded in
rendition.

27. If you are a Computer Scientist
n Your knowledge and concepts for design of
software applications may fit to technical
authoring done by others in your content
management system.
n Using plain language instead of computer
language doesn’t make a big difference.
n Communicating concepts, tasks and references is
close to writing an application.

28. If you are an Information Architect
n Assess modularization strategy based on
n abstraction
n encapsulation
n inheritance
n information hiding
n Check the metadata and filter properties
n to support generic, specific, and complex topics
n to reduce the overall complexity of the topics

29. If you are a Technical Writer
n Check the complexity and modularization of your
topics.
n You may already write according to the principles you
heard today.
è Move from intuition to fact based modularization.
n You may find opportunities
n to reduce complexity in single topics,
n to reduce likelihood for change of your topics,
n to increase reuse of text moved to generic topics.
è Reassess your modularization strategy

30. Summary
n DITA specification and Open Toolkit are based on
principles of OOP.
n OOP principles are state-of-the-art in computer
science – but they are not the best pick for all
applications.
n Engineers embrace OOP and can apply its
principles to modularization of topics written for
technical documentation to reduce complexity and
updates and to increase reuse.

31. Thank you for your Attention!
n Questions?
n Contact info: ghkrause@web.de

32. Resources
n Steve McConnell, Code Complete, 2004
n Michael J. Chonoles, James A. Schardt,
UML 2 for Dummies, 2003
n And of course many pages in Wikipedia including
n http://en.wikipedia.org/wiki/Object-oriented_programming