6 Replies Latest reply: Jul 30, 2013 3:32 PM by shawninvancouver RSS

    Authoring documentation (200 - 400 pages)

    shawninvancouver Community Member
    shawninvancouver Jul 29, 2013 6:06 PM

      Hello all,

       

      Just a little background, I am an experience technical writer who has used primarily Word (for shorter documentation) and FrameMaker (for larger documents).

       

      Now, I am in a position to choose a publishing tool.

      I currently own:

      • Word 2013 (happy to continue to use this for shorter quick/dirty documentation)
      • Creative Cloud

       

      My choices for documentation (for various reasons) are currently [cost is not a number one concern]:

      • FrameMaker (for familiarity reasons)
      • MadCap Flare
      • Sphinx (I was asked to look into this tool but reStructuredtext doesn't appeal to me and even offer the formatting flexibility I require)

       

      Requirements:

      • Must enable OS agnostic collaboration (usually just markups and commenting)
      •   NOTE: My current solution is to output as PDF and save to Crocodoc personal (check them out!)
      • Single source documentation that will output/accommodate (with little or no edits) to the following formats: XML/HTML5 (web publishing), PDF, and potentially CHM help format
      • Better or similar content control as Word or Framemaker
      • Must scale well for large documentation
      • Corporate requirement: must play nice with git (gitorious.org) for source control
      • Good community support (Adobe products win in this category)

       

       

      Questions:

      1. Are there any suitable tools, that meet all the above criteria, in the Adobe CC that I could leverage?
      2. If 1) is a negative, how well does FrameMaker compare against MadCap Flare?
      3. Are there any other tools I should consider?

       

      Thank you

        • 1. Re: Authoring documentation (200 - 400 pages)
          shawninvancouver Community Member
          shawninvancouver Jul 30, 2013 10:01 AM (in response to shawninvancouver)

          Hmm.... no responses.

          • 2. Re: Authoring documentation (200 - 400 pages)
            Piem3D Community Member
            Piem3D Jul 30, 2013 12:30 PM (in response to shawninvancouver)

            Hello

            We are also making +200 pages documentations for naval sector.

            You should try Indesign that can handle structured imports and dtd.. (that's all for the present time)...and even if we do not use xml because the documentation is essentialy  for print, i did some tries pretty quickly.

            Indesign got features framemaker doesn't have and vice versa (too bad) but it's at least a "must try" in your case.

            For the collaboration part.. we do not want and never rely on any other server than our, and we are working with subversion. (tortoise for those on pc, and "zenaware cornerstone" for the mac users because we have mac and pc, and all is going fine.

            • 3. Re: Authoring documentation (200 - 400 pages)
              John Waller CommunityMVP
              John Waller Jul 30, 2013 2:19 PM (in response to shawninvancouver)

              Questions:

              1. Are there any suitable tools, that meet all the above criteria, in the Adobe CC that I could leverage?
              2. If 1) is a negative, how well does FrameMaker compare against MadCap Flare?
              3. Are there any other tools I should consider?

              1. Adobe Robohelp is the product which immediately springs to mind, but that's a separate purchase - not a Cloud product.

              http://www.adobe.com/products/robohelp.html

               

              2. Don't know. Never used either.

               

              3. I have used Help and Manual for several years. It's strong, versatile product and very actively developed. Don't know if it will suit all your needs though. You can download a free trial version.

              http://www.helpandmanual.com

              • 4. Re: Authoring documentation (200 - 400 pages)
                shawninvancouver Community Member
                shawninvancouver Jul 30, 2013 2:24 PM (in response to Piem3D)

                Thank you for your reply Piem3D.

                 

                I am intrigued by Indesign, mostly because it is already part of my CC subscription. But I asked around a while back and some concerns came up.

                 

                From what I understand, when comparing Indesign to FrameMaker, it seems that Indesign isn't the best tool when you need:
                - To exceed 100 pages
                - Complex TOCs and Indexes

                - Footnotes (no support?)

                - Localization (support for translation to other langauges)

                - No git support (version control)

                 

                Please corrent me if I am wrong.

                • 5. Re: Authoring documentation (200 - 400 pages)
                  John Waller CommunityMVP
                  John Waller Jul 30, 2013 2:37 PM (in response to shawninvancouver)

                  How important is single source authoring/multiple format output for you?

                   

                  Dedicated Help Authoring Tools (HATs), including RoboHelp/MadCap Flare/Help & Manual and others, are an industry in themselves.

                  http://en.wikipedia.org/wiki/Help_authoring_tool

                   

                  Word, Indesign and Framemaker are not really aimed at that market - although they are obviously suitable for certain workflows which overlap with HATs.

                  • 6. Re: Authoring documentation (200 - 400 pages)
                    shawninvancouver Community Member
                    shawninvancouver Jul 30, 2013 3:32 PM (in response to John Waller)

                    Hello John,

                     

                    I realize that I am almost talking about two different animals (re: documentation authoring vs help authoring) but it seems to me that some tools have successfully merged these two requirements. I am sure you are aware that it is becoming more common that  technical writers author content for digital media via PDF and web publishing (i.e. HTML or help formats).

                     

                    From what I see of MadCap Flare, it seems to successfully blend most of my requirements; they certainly make a compelling argument for switching from Adobe FrameMaker (and InDesign) to MadCap Flare. Please don't misunderstand, I have not made a decision yet. In fact, I would LOVE to be convinced that InDesign will do everything I require (or at least all the most important requirements). Ultimately, I wish to ensure that I make an informed decision before I turn away from Adobe products.

                     

                    >How important is single source authoring/multiple format output for you?

                     

                    Very important... but CHM or other help formats are not as important as:

                    - Scalability (reliable content design - even with a 400 page count)

                    - External content links (i.e. images for easy updating)

                    - Links with relative paths (for portability)

                    - Very flexible layout design

                    - Flexible indexing, TOC, Footnotes

                    - Output PDF, XML, HTML5

                    - git version control is still a nice to have

                     

                    I think those are my main requirements.

                     

                    I would love to see some samples of .indd examples but web searches have only turned up example templates.

                     

                     

                    Thank you for your help.