by Liz Fraley
This is the fourth of a series of articles based on the talk I gave at the Content Management 2005 conference. These articles focus on extending single-sourcing systems and activities to integrate content-generating organizations enterprise-wide.
Source includes any programs that a company uses in house—or integrates with. Usually we think of source as software product source code. There’s more to source code than the software product. There’s documentation in the source code. There’s feature information in the source code. All of this is source for documentation development. Where can source be found? In product source code. In the marketing materials. In the price list. It’s even in the approval chain that authorizes product release.
Sometimes source isn’t obvious. Everywhere in an organization are simple tools that you don’t even know people are using. It’s in all the little ways employees track their activities and responsibilities. It’s all the things that people do to import information, but that no one even thinks of as “source.”
At one client site, a writer I knew developed a huge spreadsheet that would let him track the features that he and his team needed to document for a release. It tracked status, responsible party, due dates and engineering contacts, and other publications-specific information. He had one of these spreadsheets for every one of the five releases he was either managing or working on. In every instance, he filled out the spreadsheet by hand with tedious, strict attention to detail.
For a long time, no one knew he was doing it. Eventually, maintaining it became second nature. It provided him with an extremely accurate picture of the state of the documentation. He could respond to management’s questions easily, and he was always on top of issues the minute they arose. But he was always working late, always stressed out, because managing all this information by hand was extremely time consuming, even for all the benefit the department got out of it. His experience is not unique. These kinds of tools are everywhere in your organization. And they are always manual, time-consuming systems.
Every good management structure wants to encourage employees to automate for efficiency. If you want to make people more efficient, it’s extremely important to find these tools and create more efficient tools to improve employee productivity. By improving productivity and automatically collecting that information about information (metadata), you improve source generation.
Source is anything that inspects data and is dependent on it’s structure. Dependencies equal time lost to invisible causes anytime something changes. Anywhere. Source is just a kind of information. It is a very specialized kind of information, with specialized uses.
- Filters and transforms information (database, statistical tools)
- Collects information (web apps, assay machines)
- Produces information (simulators, …)
Source code is itself a product, whether internal or external. Some parts of the source code may be aimed at internal developers, end-users, or other source developers (partners). Source code can be a driver toward information exchange in others. Businesses are driven by process, but that process can change. Ideally, processes are specified. In reality, most processes are ad hoc with guidelines.
Documentation can take advantage of levels of information, the gradations of detail, in order to produce two versions of the same manual. One version of manual may include the detailed API available to engineering while another version of the same manual might leave out the huge sections of the API that are unavailable to external end users. The varying level of detail built into the source code can drive the way that the documentation is constructed.
Where Does Source Come From?
Source is created by source makers. These people create new content that stands alone. They also create the content that gets pushed back into a product. Source is created by source annotators. The product might itself have provided metadata that was the basis for the newly-created content, in either structural or template form. Annotators take chunks of generated material, shape it, and flesh it out. Source comes from every part of the organization. Anyone who is creating or annotating source can be included in efficiency initiatives.
Get useful tips and valuable resources every month
Join the thousands who know just how much we share.