[Framers] I'm pretty sure the answer is structured content with DITA but I'll ask anyway

Norton, Michael Michael.Norton at pega.com
Wed Jul 27 13:37:37 PDT 2016


I worked in an environment that sounds somewhat similar to your's for a few years. I produced "comprehensive" Release Letters that sometimes reached 300 pages. Each new feature was discussed in its entirety and I was also the lone writer. I argued against that approach, but I did not win that argument and given that I was going to remain a lone writer, it proved to be workable.

I tried to write each feature description in a way that would match its target book, so after the software and the Release Notes were released, I could fairly quickly go back and update the various manuals. It was then mainly a matter of cutting and pasting with some minor tweaks. A release might consist of 80 features and the doc for each could require a paragraph or 20 pages. Each feature was documented in a single Frame file and these files were pulled into the Release Notes document as insets.

I would identify where the new information would go in the existing doc set when I began working on a feature. If the feature was pretty solid, I might even go ahead and place it in the target book. Usually, within a month or so of the software release, I had the books up-to-date.

This was done in unstructured Frame. There were a total of 60 manuals in the doc set, but only 10-15 were typically updated with each release.

Now, being the only writer for 30+ developers, I mainly put out a lot of fires. It was hard to do more than make incremental improvements to anything. I did consider trying to move to a structured workflow, but given the size of the doc set, the workload, and the resources available (me), it just didn't seem practical.


More information about the Framers mailing list