tag:blogger.com,1999:blog-4577906602302829844.post5790350426905955926..comments2023-06-05T00:53:11.609-07:00Comments on Barbara's View: CMS or Version Control - which one for documentation?Barbarahttp://www.blogger.com/profile/06012072032770187301noreply@blogger.comBlogger5125tag:blogger.com,1999:blog-4577906602302829844.post-75509374004000807472012-07-17T10:03:03.352-07:002012-07-17T10:03:03.352-07:00Thanks for the feedback Yappa. It has been a long ...Thanks for the feedback Yappa. It has been a long while since I posted this and about 2 years since I have been working in the industry. I am sure in the last 2 years the technology has changed significantly. I appreciate your view and even though this is an old post thanks for taking the time to make your voice heard.<br />Cheers, <br />BarbBarbarahttps://www.blogger.com/profile/06012072032770187301noreply@blogger.comtag:blogger.com,1999:blog-4577906602302829844.post-62715975601927951412012-07-17T08:17:26.914-07:002012-07-17T08:17:26.914-07:00I arrived at this post really late (4 years in fac...I arrived at this post really late (4 years in fact), so this may never be read, but what the hay...<br /><br />To compare a version control system and CMS, you need to be clear about what you're comparing: not XML in the CMS versus Word in the source control (as seems to be going on here), but XML in both.<br /><br />Also, doc files in a version control system can and should have meaningful file names. In fact, file names for the code should too! There's no technical reason to have non-meaningful names.<br /><br />Searching is actually usually easier in version control, because you can do something simple like grep. Likewise, you can easily write scripts to make global changes across a great many files at once.<br /><br />CMSs should have easy search, but in my experience they don't. They are relational databases and tend to be opaque. Because the doc market for CMSs is relatively small, CMSs are optimized for a wide range of products and they never seem to work well for whatever I'm working on. There is a steep learning curve to using one effectively, especially for things like search.<br /><br />I have never used a CMS that made it possible or easy to make global changes across a doc set, either.<br /><br />Responding to a comment: CMSs provide no advantage in the ability to reuse topics, conrefs, file references, etc. in DITA or Docbook.<br /><br />So when is a CMS useful? Perhaps in large, complex doc environments with lots of writers. Eg if you are a hardware manufacturer with a lot of models of product that require huge reuse of documentation and the docs are localized into many languages.<br /><br />If you buy a CMS, you'd better have a skilled tools team to troubleshoot, as well, because (again in my experience) CMSs have many bugs and there are many glitches.<br /><br />Finally, they're brutally expensive.Yappahttps://www.blogger.com/profile/18126433451905766475noreply@blogger.comtag:blogger.com,1999:blog-4577906602302829844.post-76179668971071340342012-07-17T08:16:38.513-07:002012-07-17T08:16:38.513-07:00I arrived at this post really late (4 years in fac...I arrived at this post really late (4 years in fact), so this may never be read, but what the hay...<br /><br />To compare a version control system and CMS, you need to be clear about what you're comparing: not XML in the CMS versus Word in the source control (as seems to be going on here), but XML in both.<br /><br />Also, doc files in a version control system can and should have meaningful file names. In fact, file names for the code should too! There's no technical reason to have non-meaningful names.<br /><br />Searching is actually usually easier in version control, because you can do something simple like grep. Likewise, you can easily write scripts to make global changes across a great many files at once.<br /><br />CMSs should have easy search, but in my experience they don't. They are relational databases and tend to be opaque. Because the doc market for CMSs is relatively small, CMSs are optimized for a wide range of products and they never seem to work well for whatever I'm working on. There is a steep learning curve to using one effectively, especially for things like search.<br /><br />I have never used a CMS that made it possible or easy to make global changes across a doc set, either.<br /><br />Responding to a comment: CMSs provide no advantage in the ability to reuse topics, conrefs, file references, etc. in DITA or Docbook.<br /><br />So when is a CMS useful? Perhaps in large, complex doc environments with lots of writers. Eg if you are a hardware manufacturer with a lot of models of product that require huge reuse of documentation and the docs are localized into many languages.<br /><br />If you buy a CMS, you'd better have a skilled tools team to troubleshoot, as well, because (again in my experience) CMSs have many bugs and there are many glitches.<br /><br />Finally, they're brutally expensive.Yappahttps://www.blogger.com/profile/18126433451905766475noreply@blogger.comtag:blogger.com,1999:blog-4577906602302829844.post-51213436639477286522008-01-27T07:18:00.000-08:002008-01-27T07:18:00.000-08:00Great post. This gave me a much better understand...Great post. This gave me a much better understanding of how important a CMS really is for an efficient documentation system.Anonymousnoreply@blogger.comtag:blogger.com,1999:blog-4577906602302829844.post-24992745079793094772008-01-23T19:18:00.000-08:002008-01-23T19:18:00.000-08:00Unit of work is a construct that highlights an imp...Unit of work is a construct that highlights an important difference between a source code manager (SCM) and a content management system (CMS). In a SCM the unit of work is a release. You'd store all the executables required to build a given release as a stand alone package with no dependencies such that they could be compiled into an executable and released. In a CMS the unit of work is a published output composed from files that are likely living independent lives. The ability to manage "referenced to" and "referenced from" for each file is critically important for a CMS and non-existent in an SCM. As a result a CMS is designed differently than a SCM. An example will highlight the consequences of this design difference. Consider a caution that is used across many products and therefore appears in many documents (ie. do not submerge power chord in water or severe shock will result). If you’re using an SCM to control your content that caution would be copied and pasted many times over. In a CMS it would be written once and used by reference. Can you afford the time it takes to track down and change all occurrences of that caution? Can you manage the risk of missing one of those cautions and having it result in a product liability lawsuit? Where the economies and certainty of reuse are required your really can’t afford to do a CMS’s job with an SCM. As technical communicators we’re under exponentially increasing pressure to “write once and use many” so we need to articulate which is the right tool for the job at hand.Anonymousnoreply@blogger.com