do you think oop when writing topics?
TRANSCRIPT
Do You Think OOP(Object-Oriented Programming)
When Writing Topics?
by Gunnar H. Krause
Why do we talk about Programming?
D I T A
HTML
DOCBOOK
XML
OOP
Minimalism
other
Authoring Best Practice
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
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 hasn 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.
What about Non-OOP?!
n Example: procedural programmingn 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.
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 systemdoes not enforce user-friendly and easyto maintain documentation, either.
What to Learn?
n Understanding the basic principles is needed.
n Experience is needed as well.
What is an Object in OOP?
n An object is something withn a unique namen propertiesn methods that can be performed with it
n My carn Registration plate number M-GK1n Driver window 75% open, engine stoppedn Ability to close a window, start engine
NameProperty_AProperty_B
Method_1()Method_2()
M-GK1WindowLeftEngine
WindUp()Start()
Abstraction
n Ignore unimportant details for a certain level of aggregationn 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.
Encapsulation
n Encapsulation is an imperativen 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.
Inheritanceby 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 methodsn Add properties
or methods
ConvertibleRoof
OpenRoof()
eCarBatteryLevel {FuelLevel}
LoadBattery(){FillTank()}
CarFuelLevel
Engine
FillTank()Start()
Inheritance (2)
n A link between two specific classes is established.
n You can easily detect commonalities versus specific characteristics.
n Inherited associationsn 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.
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.
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.
Bridge to DITA Specification
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”).
Bridge to DITA Specification
n Class methods are handled by the open toolkitn Resolving conref informationn Creating links between topicsn Formatting title and using it as link textn Embedding images
n It is defined once how something like a <title> behaves in an html or PDF context.
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
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
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 technologyn a specific 1Gbit DDR3 DRAM project in 70 nm
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.”
Improvements
n Happy readersn 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.
Topic Categories Introduced by Gunnar
n New metadata to handle topics in CMSn Generic (topic)n Content is applicable to a range of projectsn Information is unlike to change and ready for reuse
n Specific (topic)n Content is specific to a projectn 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.
Rendition
n For internal publishingn Keep separate lists or concepts to emphasize what is
common or specific across productsn Filter complex topics to fit product
n For external publishingn Merge lists and concepts for integrated text flown Filter complex topics for external readers
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”.
Information Hiding in Authoring
n Separate information according to reliabilityn Stable or approved information
n Transient or preliminary information
n Separate topics reduce scope of change.
n Unreliable topics can be marked or excluded in rendition.
Features of DDRx Standard – Consensus List• Supply Voltage of 1.2 V• FBGA Package
Potential Features of DDRx Standard• Low density components: 512 Mbit and 1 Gbit• Burst chop mode
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.
If you are an Information Architect
n Assess modularization strategy based onn abstractionn encapsulationn inheritancen information hiding
n Check the metadata and filter propertiesn to support generic, specific, and complex topicsn to reduce the overall complexity of the topics
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
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.
Resources
n Steve McConnell, Code Complete, 2004n 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