• Documenting APIs & SDKs     
  • Just Enough C and C++     
  • Just Enough Java     
  • Understanding Complex Software     
  • About the Lecturer     
  • Satisfied Clients     
  • Testimonials     

    • Documenting APIs and SDKs
    Manuel Gordon

    The Rave Reviews are In!
    		•  "I'm excited by the fact that I now feel able to READ and UNDERSTAND the code I spend most of the time cutting and pasting!"
    		• "Even though I know some of these concepts, having them presented in a global view is interesting and refreshing."
    		• "I got great feedback, affirmation, motivation to get the job done right."
    		• "This course is amazing for tech writers new to API writing."
    		• "Builds a writer's confidence that they are on the right track to developing acceptable SDK documentation."
    		• "All the information was fabulous... Covered a lot of ground in only two days."

    Participants Agree: Workshop is Tops
    As these comments show, the recent presentation of this workshop in Montreal was a smash hit! The participants had a vast range of experience. There were some just getting started with API docs, and others who'd been writing them for years. There were some with little programming experience, and others who were seasoned Java or C++ programmers. But they all agreed on one thing: this workshop is tops!

    Workshop Overview
    "Help wanted: Technical Writer to document SDKs. Must have Bachelor's degree in Computer Science, Master's degree in Technical Communication, plus five year's experience in a similar position..."
    In their dreams! In the real world, there are a lot more SDKs that need documenting than technical writers with the ideal qualifications.
    Documenting SDKs isn't easy, and it's not for everyone. But it is a highly sought-after skill. It's work that will earn you respect, both from other writers and from programmers.
    Sure, it's a tough job, but somebody's got to do it. Why not you? Or if you're a publications manager, why not be that hotshot in your department?

    Er, what's an API?
    An Application Programming Interface (API) is the interface that software presents to programmers who need to build applications on top of that software. If you can package that API with useful documentation and good sample programs, you have a Software Development Kit (SDK) your company can sell. No documentation, no SDK!
    Programmers and marketing people often use the therms "API" and "SDK" interchangeably.
    To document an SDK, you should learn something about the programming language it was written in, usually C or C++. But you don't need to write programs yourself. After all, a technical writer doesn't need to understand everything going on beneath the user interface to document a software product. You do need to understand something of the design issues that SDK developers face. And you need to understand the very different problems faced by the very different programmers who will actually use the SDK, in other words: your audience.
    Documenting APIs and SDKs isn't for everyone. You should start with a good technical orientation. And then take this two-day workshop from Gordon & Gordon!

    What will this workshop give me?
    This 1-day workshop focuses on how to organize and produce SDK documentation, no matter what programming language the API is written in. You'll learn why companies bother with SDKs, what programmers want and why sample programs are so important.

    For full details, see What You Will Learn .

    Do I need to be a programmer?

    To document an SDK, you should learn something about the programming language it was written in... usually C, C++ or Java.

    Yes, there are lots of thick books and lengthy courses that will teach you how to program in those languages. But that's overkill for a tech writer with an urgent deadline. So Gordon & Gordon developed three 1-day workshops that cover exactly what you need to know about each language - and more...

    Who Should Attend
    		•  Technical writers with a capital T
    		• Writers who've had some exposure to computer programming (in any programming language)
    		• Writers or programmers now being asked to document SDKs
    		• In-house writers or consultants who want to break into the lucractive field of writing SDKs

    Learning Objectives
    At the end of this workshop, you will be able to work with software developers to create useful documentation for a Software Development Kit (SDK).

    What You Will Learn

    Why Bother with SDKs
    • Why software vendors sell SDks
    • Why customers buy SDKs
    • How programmers use SDKs

    What SDK Documentation Looks Like
    • The Reference Manual
    • The Developer's Guide
    • Other forms of online and embedded documentation
    What Programmers Really Want in an SDK
    • Code, code, and more code
    • The differences between code snippets, sample programs, and full-fledged demo programs
    • How to specify code samples that are useful to your readers
    • How to embed sample code in documentation
    Generating Reference Documentation
    • Embedding documentation in code
    • The benefits of generating (vs. writing) reference documentation
    • How Javadoc, doxygen, Document X and similar tools work
    The Outline for a Developer's Guide
    • Introduction, Installation, Getting Started, Task 1, Task 2,... Appendices
    • Applying the Universal Tasks
    • Determining the tasks that API users (programmers) actually perform
    • Avoiding the great ugly Theory chapter
    • What goes into the Installation chapter
    • Building chapters around sample programs
    Documentation Strategies
    • Applying USE (Understand, Simplify, Explain) to SDKs
    • "User Manual as Spec"
    • Building documentation teams that include programmers
    • Typical documentation plan for an SDK
    • When to bring in a consultant
    • Getting access to code and developers' tools
    • Educating yourself further


    Just Enough C and C++
    Manuel Gordon

    Workshop Overview

    Tired of formatting and polishing the programmer's notes? Learn just enough C and C++ to decode header files, and then you can start writing documentation.

    You don't need to know everything. You just need to be able to decode some of the source code, extract some key information, and use your knowledge to convert that information into useful documentation.

    In this workshop we present just enough C and C++ to get you decoding the header files used in every API written in those languages. You will see and work with real-world APIs for real products. After this workshop, you will be able to use your understanding of those header files to start writing documentation—instead of simply cutting, pasting and formatting the programmers' notes.

    For full details, see "What You Will Learn .

    What else should I know?

    To succeed with an API project, you also need to understand how to organize and produce SDK documentation, especially the how-to information that belongs in a Developer's Guide. You should understand why companies bother with SDKs, what programmers want and why sample programs are so important.

    This information is not easy to find. It's not on the Web. It's not in any book on technical writing or C/C++ programming. And it's certainly not in any book written for "Dummies" or "Complete Idiots"!

    That's why Gordon & Gordon developed a 1-day workshop that covers all this material: Documenting APIs and SDKs

    Uh-oh. My company's APIs are in another language.

    Programmers may hotly debate the virtues and defects of different programming languages. Technical writers can be more relaxed: much of what we need to know to document APIs doesn't change very much if we switch from one language to another.

    If your API is written in Java or C# (sometimes called .NET), we recommend another of our 1-day workshops: Just Enough Java

    Who Should Attend

  • T echnical writers with a capital T
  • Writers with some previous exposure to computer programming (in any programming language)
  • Writers or programmers being asked to document SDKs written in C or C++
  • In-house writers or consultants who want to break into the lucrative field of writing SDKs.

    • Learning Objectives

    At the end of this workshop, you will be able to decode C or C++ header files and make an educated guess about the purpose of each function. And you will be able to work with C or C++ software developers to create useful documentation for a Software Development Kit (SDK).

    What You Will Learn

    A First Look at APIs

    Just Enough Background
    • Programming languages: there are many!
    • Origin of C and how it affects documentation
    • Origin of C++ and how it affects documentation
    Just Enough C Syntax
    • Functions: black boxes that do something very specific
    • Types: numbers, characters, strings and other kinds of data
    • Parameters: what goes into a function
    • Return values: what comes out of a function
    • Signatures: all an API user needs to know... mostly!
    • Structures: collections of data
    • Pointers to data
    • Pointers to pointers
    • Enumerated types and other special types
    • Decoding and documenting C header files
    Just Enough C++ Syntax
    • Nothing in C is alien to C++
    • Classes that combine properties (data) and methods (functions)
    • The relationship between objects and classes
    • Constructors and destructors
    • Inheritance, polymorphism and all that good object-oriented stuff
    • Decoding and documenting C++ header files
    Bonus Topics
    These bonus topics are included in the workbook but will be covered only if time permits.
    • Documenting components:
      COM, CORBA, DCOM, ActiveX... but mostly IPL
    • Generating reference documentation with doxygen and other tools

    Note: Just Enough C or C++ is a new workshop, but much of the material is adapted from the 2-day version of Documenting APIs and SDKs, an earlier workshop that Manuel Gordon has presented several times.

     Just Enough Java
    Manuel Gordon



    Workshop Overview

    Tired of formatting and polishing the programmer's notes? Learn just enough Java to decode Java source files, and then you can start writing Java documentation.

    You don't need to know everything. You just need to be able to decode some of the source code, extract some key information, and use your knowledge to convert that information into useful documentation.

    In this workshop, you will learn just enough Java to get you decoding .java source files well enough to write useful documentation. We will show you how to use javadoc, Sun's documentaton generation program for Java.

    We will also introduce Microsoft's new C# language (sometimes called NET) and show you the key differences between documenting C# and documenting Java. You will do exercises where you document a real API from a real product.

    After this workshop, you will be able to use your knowledge of Java to start writing documentation, instead of simply cutting, pasting, polishing and formatting the programmers' notes.

    For full details, see What You Will Learn .

    What else should I know?

    To succeed with an API project, you also need to understand how to organize and produce SDK documentation, especially the how-to information that belongs in a Developer's Guide. You should understand why companies bother with SDKs, what programmers want and why sample programs are so important.

    This information is not easy to find. It's not on the Web. It's not in any book on technical writing or Java programming. And it's certainly not in any book written for "Dummies" or "Complete Idiots"!

    That's why Gordon & Gordon developed a 1-day workshop that covers all this material: Documenting APIs and SDKs .

    Uh-oh. My company's APIs are in another language.

    Programmers may hotly debate the virtues and defects of different programming languages. Technical writers can be more relaxed: much of what we need to know to document APIs doesn't change very much if we switch from language to another.

    If your API is written in C or C++ we recommend another of our 1-day workshops: Just Enough C and C++

    Who Should Attend

    • T echnical writers with a capital T
    • Writers with some previous exposure to computer programming (in any programming language)
    • Writers or programmers being asked to document SDKs written in Java
    • In-house writers or consultants who want to break into the lucrative field of writing SDKs.

    Learning Objectives

    At the end of this workshop, you will be able to decode Java source files and make an educated guess about the purpose of each function. And you will be able to work with Java software developers to create useful documentation for a Software Development Kit (SDK).

    What You Will Learn

    A First Look at APIs

    • What is an API?
    • The difference between an API and an SDK
    • Who is the user of an API?
    • How javadoc tells you what you need to know
    • Classes and objects, methods and properties
    • Buzzword soup: methods, member functions, functions, properties
    • The user interface of a Java method
    • Documenting that user interface
    • Determining a method's name, purpose, parameters and return value
    • Our focus: converting source files to documentation
    Just Enough Background
    • Programming languages: there are many!
    • Origin of C and C++ and their relationship to Java
    • Origin of Java and how it affects documentation
    • The Java 2 SDK
    • Java Integrated Development Environments (IDEs)
    • Applets and applications
    • JavaBeans and Enterprise Java Beans
    • Origins of C#, .NET and Web services
    • Microsoft, Sun and the politics of programming languages
    Just Enough Java Syntax
    • Methods (functions): black boxes that do something very specific
    • Types: numbers, characters, strings and other kinds of data
    • Parameters: what goes into a function
    • Return values: what comes out of a function
    • Signatures: all an API user needs to know... mostly!
    • Private and public: controlling access to methods and properties
    • Bundling classes into packages
    • Java interfaces: the how and why
    A Little Bit of C#
    • How Java and C# are very similar
    • The differences between Java and C#
    • How these differences affect documentation
    • Documentation generation programs for the Microsoft universe


    Understanding Complex Software
    Manuel Gordon

    Workshop Overview

    "SUPERDUPER provides a comprehensive infrastructure for application services, along with object-oriented tools and components for building a three-tier network security management framework for all platforms including mainframes, UNIX, Linux and Windows. It includes a powerful X server, an extremely flexible text-based terminal emulator, a Windows Explorer-based FTP client and more!"

    If you are a technical writer, instructional designer, trainer, or marketing person who needs to explain products like this, then we have the workshop for you!

    Looking below the surface

    If you're working on a complex software project, you need to understand what's going on below the user interface. And there's a lot going on down there.

    Scratch below the surface of any big system and you quickly find clients and servers, controls and widgets, middleware and middle-tiers and n-tiers, classes and objects and instances, methods, properties, functions and procedures, COM and CORBA and ActiveX, Web services and application services, and yes: UNIX systems even have daemons!

    Do you understand all this? Can you hold up your end of a conversation at your workplace? Or do you need a good workshop to help you understand what the developers and engineers are talking about?

    Who Should Attend

  • Technical writers and instructional designers and trainers who need to explain complex software to system administrators or programers.
  • Technical writers who work on Installation and Operation manuals, SDKs, and design documentation (such as functional specifications).
  • Marketing people who need to create promotional literature for complex software.
  • Anyone in the industry who wants to better understand how computer programs work.

    • Learning Objectives

    At the end of this workshop, you will be able to understand and explain complex multi-component, multi-platform, multi-everything software either in documentation, marketing materials or training guides.

    What You Will Learn

    The visible components of software

    The (usually) invisible components of software

    • Functions and procedures
    • Classes and objects
    • Methods and properties

    The code stored on a PC

    • Executables
    • DLLs
    • The relationship between APIs and DLLs

    Running Code

    • Processes
    • Threads
    • Services
    • Daemons

      The layers (software components) of a system

      • Front ends and back ends
      • Clients and servers
      • N-tiers and middle-tiers

      Beyond the PC

    • Mainframes
    • UNIX and Linux
    • NT
    • PDAs and wireless devices

      Connecting all the Layers

    • Communication protocols
    • Middleware
    • Terminal emulators

      Designing layers to be easy to connect

    • COM and DCOM
    • ActiveX
    • CORBA

      Connecting the entire universe with Web services

    • .NET
    • J2EE
    • XML
    • SOAP

      Modeling complex software with old-style diagrams

    • Data flow diagrams
    • Entity-relationship diagrams
    • State-transition diagrams
    • Structure diagrams

      Modeling comples software with object-orientated diagtrams

    • UML
    • Object relationship diagrams
    • Use case diagrams


     What People Say about this Workshop

    Note: Understanding Complex Software is a new workshop, but much of the material is adapted from System Design, an earlier workshop that Manuel Gordon has presented many times, including at two international STC Conferences.

    Here is a selection of comments on the relevant parts of System Design:

    "Excellent! Exactly what I've needed since I became a tech writer in a software environment."
    "Packed with useful information. Very well-prepared. Articulately delivered. Just superb!"
    "Discussion of buzzwords was very helpful, since so many new ones crop up daily."
    "All in all, this was a day well spent. The part about diagrams was very useful—especially the use cases. This is a good way to look at things."
    "Well-paced, level not too deep for me to comprehend, good mix of activities and lectures. I appreciate the personal workbook as well as the refences to supplemental reading materials."
    "Knowledgeable, excellent presenter."
    "The presenter's knowledge was impressive. And I appreciate the bibliography."
    "Mr. Gordon is very knowledgeable about his subject and was able to impart this information extremely well—a great teacher!"
    "Underscored the importance of the 'technical' in technical writing... something that we need to be able to do more and more."
    "The speaker was interesting and entertaining. The material was well-organized. The slides were well-prepared. And the workbook allowed for all the scribbling that anybody could possibly desire."
    "I'd take another course from Gordon & Gordon."





     About the Lecturer
    Manuel Gordon

    Manuel Gordon is a technical writer, programmer, and computer science professor. He first studied programming at the University of Toronto, where he also worked as a computer consultant for academic and corporate researchers. Later, he did graduate work in Computer Science at McGill University.
    After moving to Montreal, Manny first worked as a statistical programmer for McGill University. While there, he upgraded the algorithms used by a popular statistical package by ripping out old, bug-ridden code, and replacing it with calls to a modern, API-based library of mathematical and statistical routines.
    He then turned to custom database programming for a company now known as FRI Corporation. At FRI, Manny worked on a pioneering, interactive, data warehouse project for the Bank of Montreal. Manny designed a major part of the API, implemented it, and of course, documented it.

    Since then, Manny has divided his time between teaching and consulting. He is a professor of Computer Science at Vanier College, and has worked as a technical writer or programming consultant for many companies.
    His resume is sprinkled with names such as DMR, CGI, Hummingbird, Softimage, and even Microsoft.
    As a technical writer, Manny specializes in documenting APIs, SDKs, and complex data communications software.
    Since 1997, Manny has been a partner in Gordon & Gordon, which is best known for developing and delivering lively, interesting, useful workshops in technical and marketing writing.


     Satisfied Clients

    The list of our satisfied clients includes:

  • 20-20 Technologies - Quebec - Canada
  • Alchemedia - Israel
  • Amdocs (Israel) Ltd
  • AnySoft - Israel
  • Attunity - Israel
  • Audiocodes - Israel
  • B M C Software - Israel
  • Cimatron - Israel
  • Critical Path Inc. - Toronto - Canada
  • Discreet Logic - Montreal - Canada
  • Excalibur - Israel
  • EZChip - Israel
  • FileNET Corporation - Costa Mesa, CA, US
  • Gemplus Toronto - Canada
  • I D S I Advanced data Systems - Israel
  • Innovatia St John, New Brunswick - Canada
  • InSyst Ltd - Israel
  • Intel - Israel
  • Ixiasoft - Quebec - Canada
  • Locus Dialogue - Toronto - Canada
  • Mainsoft - Israel
  • MDS Pharma Service Inc. - Toronto - Canada
  • Medcon - Israel
  • Mercury Interactive - Israel
  • MicroType - Israel
  • N D S Technologies - Israel
  • Nice Systems - Israel
  • Nuance Communications - Montreal - Canada
  • Olista - Israel
  • Olive Software - Israel
  • Optibase - Israel
  • Panorama - Israel
  • PCS Innovations - Quebec - Canada
  • Polycom - Israel
  • RAD Data Communications - Israel
  • RADVISION - Israel
  • Regisoft - Israel
  • SAP Labs Israel
  • Softimage - Montreal - Canada
  • Solidum Systems - Ottawa - Canada
  • Star*Home (Comverse) - Israel
  • Symantec - Israel
  • Teledata Networks - Israel
  • Telesat - Ottawa - Canada
  • Voice Age - Quebec - Canada
  • Whale Communications - Israel
  • Write Direction - Israel

    		•

    Testimonials

    		• "We have so much trouble finding Tech Writers who can read source files and document APIs! This course will be really, really good for the other two writers on my team."
    		• "I'm excited by the fact that I can now READ and UNDERSTAND the code i spend most of the time cutting and pasting!."
    		• "Love the exercises. I find this course is bringing everything together that I've been trying to learn on my own so far."
    		• "Overall, the course was EXCELLENT. I have benefitted ENORMOUSLY and it will help me TREMENDOUSLY in my work. I think it has been one of the most useful courses I have taken. Thank you so very much."
    		• "Love the exercises. I find this course is bringing everything together that I've been trying to learn on my own so far."
    		• "I'm looking forward to re-reading our Developer's Guide. I have several ideas how to change it for the better. Also excited by the fact that I now feel able to READ and UNDERSTAND the code I spend most of the time cutting and pasting!"
    		• "I got great info, feedback, affirmation, motivation, direction to go back and get the right job done."
    		• "I think this course is just amazing for tech writers new to API writing. We have so much trouble finding tech writers who can read header files and document APIs! This course will be really, really good for the other two writers on my team."
    		• "I feel able to analyze header files in an intelligent-enough way to produce skeletal documentation. A definite improvement!"
    		• "I wanted to stop guessing and get informed! Now I am much better prepared to do this work, and have a clue where to get supporting information."
    		• "Excellent introduction to the raison d'etre of APIs and SDKs. The course builds a writer's confidence that they are on the right track to developing acceptable SDK documentation."
    		• "All the information was fabulous... Covered a lot of ground"
    		• "Solid, basic API concepts made concrete through examples. Great presentation manner and sense of humour, depth of knowledge and experience."
    		• "Manny is a lively, very interesting instructor."
    		• "Lots of information, entertaining."
    		• "The pace is good, the content is rich. You have captured my interest and excited my learning curve."
    		• "Fortunately, I could always work from quite complete documentation written by programmers. I just had to reformulate, reformat, and update. I never had to dig in the header files. Now, I know how to work the other way around, in case I need to some day. Today's course was really educational."
    		• "Good tips for extracting important information from code and other sources."
    		• "I have no programming background. Part of my job is to format the doc written by programmers. After this training, I am going to be able to write the doc by myself."
    		• "Manny is a very good and interesting animator."
    		• "Even though I know some of these concepts, having them presented in a global view is interesting and refreshing."
    		• "Covered a lot of ground in only two days."
    		• "A very good introduction to what it's all about."
    		• "I certainly found the course useful. It has catapulted the dialogue on what goes into our SDK up to management level."
  • Documenting APIs & SDKs     
  • Just Enough C and C++     
  • Just Enough Java     
  • Understanding Complex Software     
  • About the Lecturer     
  • Satisfied Clients     
  • Testimonials