Is the idea of single-sourced documentation dead?
asked Mar 18, 2011 at 2:21
-
I have no idea what this means, so sadly I can't be more specific if it's needed. I got the question from the closed Technical Writing SE.– Ralph GallagherMar 18, 2011 at 2:22
-
2I've seen the term "single-source" documentation used to refer to writing documentation once and using it to generate multiple outputs: web-site, help file, PDF, e-Book, physical manual etc– BevanMar 18, 2011 at 9:15
-
To answer the question in a comment. Man, I really kind of hope so.– user8356Mar 5, 2020 at 18:37
Add a comment
|
3 Answers
I do not know, why it should be dead. Writing and updating several sources with the same content is tedious, error-prone and will cost a lot of money.
The idea is to separate content and design. You write the content one time and you generate with different designs/formats websites, PDFs, books, eBooks, whatever.
The main approach is to store the content with its meta-information (e.g. paragraph begins here, paragraph ends there) into an XML file, the design information into a different file (style sheet) and let a computer program combining them. (You will have different style sheets for different formats.)
DocBook is a semantic markup language designed exactly for this purpose. You use it to define the content and the logical structure and generate the final product (book, webpage, ...) with different style sheets.
Joining John Smithers, single-sourcing is not only not dead, but increasingly vivid. There are new standards under revision right now. Darwin Information Type Architecture 1.2, for instance, was so anxiously expected that the OASIS team voluntarily leaked the working specification for users to implement, August 2010. Every single, serious, content site is based on single-sourcing: Newspapers, radios, TV stations. Not to mention the bulk of government agencies. Checkout the OASIS site and XML.org. You will find plenty of action there.
Single sourcing is definitely not dead. Its best application is within some kind of content management system so that the content not only has a variety of output options, but can be remixed and recycled for other uses. As another answer pointed out, you must separate content from formatting for single-sourcing and content management to work.
Software developers have been using a similar model for ages. If you're going to be doing the same procedure in multiple places, use a function call instead of rewriting the code every time. Put your especially useful functions into a module that you can use in other programs. Keep your source code in a source control repository so you can revert if needed, and prevent conflicting edits to the same bit of code.
