6 Replies Latest reply on Jan 25, 2012 8:07 AM by Reviewer1066

    Best practices: formatting inside or outside EDDs ?

    4everJang Level 3

      Hello all,


      A discussion started elsewhere on whether or not formatting should be done inside the EDD. I think that discussion should be held here, as there will be more people who have experience with this on this forum than on the other non-public discussion site. Of course most of the participants in the discussion on the closed forum are on this forum as, well, so we can maybe continue our discussion with a larger group.


      On this particular topic, there seem to be two completely opposite views, and I would like to hear from people on this forum what they feel about this.


      On one side are those who state that formatting should be done completely in the EDD, as this takes the ability to mess up the formatting away from authors - who should not have any control over formatting as they should just deliver content. If formatting is put in their hands the compatibility with existing standards or earlier revision processes would be breached. One message mentioned an 'enforcable controllable environment' as the goal of working with structured Frame in the first place - if I am getting that point correctly (and of not, there will be reactions from the ones on this forum who belong to that camp).


      The other side (which, according to the impression given on the non-public site, is a rare minitory viewpoint) is taking ALL formatting out of the EDD and allowing clients to do their own paragraph and character designer based formatting without having to edit the EDD. In this case, the client is not dependent on the person who created the EDD to change the font, text alignment, hyphenation etc. The EDD assigns paragraph format tags and the client can - if they want to - change those paragraph formats to suit their needs. I am a strong advocate of this position and have been using this strategy for my clients with a lot of success.


      I do want to answer to the comments about control, just to clarify that the choice between formatting inside or outside the EDD is not the same as a choice between keeping full control or having no control whatsoever. Control or no control is another matter, in my opinion. I can easily see methods to make the paragraph and character designer unavailable in Frame for those who have no authority to make any changes to the company's style sheerts. This would leave those who are in control of the styling the option to define or redefine paragraph and character styles without having to bring in the expensive consultant who created the EDD for them. Changes to the EDD would for example be required to support another font for a Bulgarian translation.


      Frankly, I do not want to make my clients dependent on my services just to change the font to Arial CYR if they happen to sell a machine to Bulgaria. Also, I don't want to build full support for all the formatting quirks my customers might ever need into an EDD that will become an almost unmanageable beast (and require expensive consultants to make any changes that do not bring the system to a screaching halt). My customers can create different templates, using different sets of fonts, paragraph formats, character formats and table formats, without ever changing the underlying structure that is defined by the EDD. It is their responsibility to define the look and feel of their documents, and it is mine to make sure the structure is correct. They pay me to build a structured authoring system, not to define their style guide. And if they do want me to create their style guide as well, I will create a template that contains all the required paragraph, character and table formats separate from the EDD. To ensure that their authors cannot mess around with the formatting I will even give them a little script that makes the designer pods go away and stay away. Plenty control, but not at the cost of putting the formatting in the EDD - where I do not think it belongs in the first place.


      OK - that was my first round. Let's hear it from the others on this forum...


      Kind regards from drizzly Amsterdam



        • 1. Re: Best practices: formatting inside or outside EDDs ?
          Wiedenmaier Level 3

          Hi Jang,

          Thanks for picking up this very interesting topic. Some years ago I switched my understanding of creating EDDs from using paragraph formats to using format change list without exception, wherever it’s possible and wise. One year ago I started a blog post on this topic http://www.practice-innovation.de/wiki/blogpost14 (sorry it’s in German).


          Which approach is used always depends on what is your thinking of XML publishing and, of course, what’s the customer’s motivation of using structured FrameMaker. In my projects customers want to fix there layout with a specific style guide (perhaps it’s my responsibility ;-)). If there’s no style guide defined at the beginning of the project the EDD is it at its end.


          So changes are only necessary in a continuous improvement process or if there are any faults in the EDD creation process. So if simple layout changes are necessary a template administrator can do it in the EDD in a more effective way, than with paragraph styles. If you want to change a font it’s solved in less than a minute, because there’s only one place to change it. With paragraph etc. styles you have to check and change each style, haven’t you? So depending on the amount of styles changing a font could take an hour or so. Don’t you think these people who are responsible for CI can’t learn changing simple layout with FCL within an hour or so? EDD is XML and it’s really easy on that level, assumed you use format change list without exception and do a little comment if necessary and not self-explanatory.


          So is making templates changeable for customers a real factor for referencing paragraph styles? Are these the costs, if there are any changes in that way? In my projects it’s really rare a customer comes to me and asks “Please, could you change the font for me?” or “Please, the left indent of my lists should be increased to 10pt”. Most customers can do this if they want, because they got a small briefing, when they got the EDD and Templates. And if they can’t do that, should I create an invoice for 10 minutes of work? If they come with such things each day, something’s completly wrong.


          When will customers come back to me, mainly? They come back with more complex scenarios. Scenarios which can’t be solved only by changing some styles. I.e. EDD should be enhanced for other document types, new content should be provided, structured and layouted, etc. And for this you often have to take a look at customer’s processes, what effects changing/enhancing publication process itself (perhaps). For this I think it is more important to have a compact EDD than having the possibility of an UI for changing styles. In my experiences an EDD based on FCL is 30% smaller than an EDD which references paragraph styles. And it’s easier to understand. This means easier ways of enhancing/changing EDDs and at the end less costs for customers.

          Enhancing a font to “Arial CYR” (BTW: who uses this in our times ;-)) not only means changing fonts. It means changing processes, because there is a new language to handle, right?


          That’s the approach XSL:FO goes of course. All is fixed in rules and styles. So why not using XSL:FO? User’s want to have the possibility to do some finishing, which can’t be done with EDD rules (or FO-Rules), and can be automated with scripts/plugins or could be done by hand (i.e. page breaks or things like “Page intentionally left blank” (see the other discussion running ;-)). And the other thing is (often but not always) creating FM XML publishing processes means less cost than creating FO processing.


          At last: All depends on processes and what’s the motivation for customers using a structured (XML) environment. It’s not a matter of control or not control.It's a matter of EDD Design.


          • 2. Re: Best practices: formatting inside or outside EDDs ?
            Russ Ward Level 4

            Hi Jang,


            This discussion has been had in these forums before... I think more than once. You are right in your assessment that there are two opposite views, but I'm not sure it is legitimate to say either is correct. While I've had my own preference, it is necessarily shaped by the needs of my personal workflow. Needs may vary.


            That said, in my work, it has always made more sense to keep as much formatting in the template as possible; that is, have the EDD  apply existing formats only. The reasons that this has made more sense is:


            - Simplicity. Trying to put all that stuff into EDD code is tedious and can be difficult to modify/troubleshoot afterwards. When formatting is applied, you may never know exactly what is coming from where. With the separation approach, you do. The format is coming from some rule associated with the element and the formatting is coming from the format. To fully realize this benefit, you have to limit the application of formats to rules at the level of paragraph-containing and text-range elements, which I think is good practice anyway.


            - Speed. Putting all formatting into an EDD can really extend its length, which in turn can really slow things down while working. The application of formats from a template; however, is lightning quick.


            - Flexibility. If an EDD defines structure rules and format application only, it is very easy to apply the EDD to another template, as long as the formats have the same name. This happened personally to me, when I had to create a different size publication with all different font sizes, etc. With the new template set up, use of my existing EDD was turnkey... just import it and go. I acknowledge that there are EDD tricks that can help facilitate a change like this as well, but that again moves into a realm of complexity that I deem unnecessary. Furthermore... although I've never needed to do this, my template is perfectly suitable for unstructured work if necessary.


            - No advantage to do it otherwise. I reject the notion of control as a benefit to locking up formatting in an EDD. If users are actively seeking to violate their job responsibilities (like following a style guide), they will find a way no matter what. The correct approach is to fire them, not spend your time and money building elaborate schemes to shut down their wanderlust.


            I think that summarizes it. The EDD I use is somewhere around 25 pages and it is blessedly simple and very quick. I like it that way.


            • 3. Re: Best practices: formatting inside or outside EDDs ?
              Reviewer1066 Level 4

              I reject the notion of control as a benefit to locking up formatting in an EDD. If users are actively seeking to violate their job responsibilities (like following a style guide), they will find a way no matter what. The correct approach is to fire them, not spend your time and money building elaborate schemes to shut down their wanderlust.



              Because I have always been on the other side of the fence with this issue, I feel a need to respond. I agree that writers should do their jobs correctly, but it is not always easy just to fire a slacker.


              The place where I now work outsources all of its technical writing, including me. In the past, it was not unusual to bring in a writer just to do one project. Getting the project done on time with the required look often translated into a writer taking shortcuts, just to get it done. The next writer that makes the next revision also takes shortcuts. It quickly explodes into documents that contain multiple versions of identical styles and other chaff.


              By moving the formatting into the EDD, it only takes a quick reimportation of the EDD with override removal to clear out the junk. Personally, I find this easier to maintain. The complexity may require more time to update, but I like the challenge.


              I will agree with Russ in that, in the end, there is no one correct answer. It all depends upon what works best for you.



              • 4. Re: Best practices: formatting inside or outside EDDs ?
                Russ Ward Level 4

                Van, you said:


                "it is not always easy just to fire a slacker"




                "it only takes a quick reimportation of the EDD with override removal to clear out the junk"


                I certainly can't argue with that. So, perhaps I'd qualify my statements with the assertion that it is more ideal to have dedicated full-time employees doing the work, in which case the need for rigorous oversight indicates a problem bigger than the EDD debate. If one finds themselves in your situation, perhaps I have to acknowledge that your approach sounds more reasonable.



                • 5. Re: Best practices: formatting inside or outside EDDs ?
                  4everJang Level 3

                  I still do not see how putting formatting in the EDD is the only method of controlling (i.e. limiting the formatting freedom of) authors who work on structured FM documents. Of course, some people will do anything to make the document look like they want it to look, but I agree with Russ that these people have a serious authority problem when they keep doing things in ways that are not acceptable in their organisation.


                  In fact, having the formatting in the EDD does not remove the options for authors to screw up the formatting in their documents. It merely allows an easy reformatting of the document by reimporting the EDD. But this is also true if the formatting is done via paragraph and character format tags - just have one template file that is not accessible for writing available and you can always re-import the formats from that template. This gives the same net result without having to put the formatting in the EDD.


                  This leaves us with two possible alternative approaches to reach the goal, which is having authors use the structure to author the content and let the formatting issues be dealt with by others (i.e. leave the formatting as it is intended):


                  1. Create the EDD in such a way that it is in fact much easier and faster to follow the given structure, instead of giving the author a quick and dirty way of making stuff look like it is correctly structured. If an author has to pick from a hundred possible elements to insert in a certain position in the file, the choice to not search for the required element but instead apply some formatting (i.e. making text Bold instead of using the Emphasis element that should be used for this) is just too tempting, especially when the deadline is near. This is one of the big problems when editing unconstrained DITA documents. In general, making the right way the most efficient way helps against most occurrences of abusing other options. People do not want to spend more time on doing what they need to do for a living.


                  2. Remove the formatting commands from the author's environment. The EDD applies styles via paragraph and character format tags and the author cannot get to the paragraph and character designer pods to make changes. If they cannot get to the commands, they will stick to the given formatting. Giving a supervisor access rights to the formatting can be done by setting specific user permissions. In this scenario, the supervisor does not need any EDD knowledge and certainly does not need to import an EDD unless there have been changes to the structure.


                  An advantage of keeping formatting out of the EDD occurs when roundtripping to XML is at stake. I do not have to include any formatting rules as processing instructions or special attributes to XML, as all format issues are handled in the tags that are completely outside the XML. Of course you might counter that you do want to have formatting info in the XML so that it comes out right in any XML-based publishing process, but that is where the use of CSS should be preferred. In fact, a CSS is not too different from using paragraph and character format tags in FM.


                  Just some more rambling from my side. Maybe food for thought - and further argumentation in this thread.



                  • 6. Re: Best practices: formatting inside or outside EDDs ?
                    Reviewer1066 Level 4

                    Further thoughts...


                    Jang brings up the scenario of XML roundtripping. If that were the required workflow, then the issue is moot. The stored content is XML only. When the XML is opened in FrameMaker, then the formatting is applied from a pristine template. Whether the formatting is done by the EDD or by paragraph and character formats is immaterial; only the correct forms are used.


                    The issue of control versus the writer's due diligence arises because FrameMaker offers the writer the ability to override the template. My workplace is in the initial stages of moving to an XML-based CMS in which the authoring is done in XMetal, which does not give the writer access to any formatting. The writer creates content only from the allowed structure. Formatting is done by the CMS at publication time. So, within a year or so, this issue may be a thing of the past for me.