Blog Article

Transforming an Ancient Website with MadCap Flare

Jack DeLand | June 26, 2024

This guest blog post was written by Jack DeLand. Jack has provided Help projects and/or Help authoring training to Fortune 50 companies around the world for over 30 years. He specializes in MadCap Flare project development, architecture, and design, and resides in Ypsilanti, a small city next to Ann Arbor, Michigan.

In the ever-evolving landscape of web design, keeping a website up-to-date is crucial for maintaining relevance and user engagement. But what happens when you inherit a relic from the past, like a website coded in HTML 4 from the year 2000? Enter Jack DeLand, a Flare advocate and Help consultant practicing since 1991, who took on the challenge of transforming a primitive site for The James Fenimore Cooper Society.

In this blog post, we’ll explore how Jack leveraged the power of MadCap Flare to breathe new life into a digital artifact, turning it into a modern, user-friendly platform while preserving its historical essence.

Yes, you too can use MadCap Flare™ to convert a website from this (left) to this (right):

Original site (left) Same site revamped in Flare (right)

Page from a typical scholarly article, old site	Same page at revamped site (identical content)

Intuition, Rejuvenation, and a Bit of ChatGPT

This time out we use MadCap Flare to transform an ancient (2000 A.D.) HTML 4 website created for The James Fenimore Cooper Society. The new site is located at https://jfcoopersociety.org/content/home.htm. Notice the icon for showing/hiding the side navigation Contents pane. The code for this popular enhancement is available at https://www.madcapsoftware.com/blog/show-hide-table-of-contents-flare/.

Cooper is best known today for his 1826 novel, The Last of the Mohicans, which has been made into multiple movies (cinematic and television) since 1909, but he wrote more than 30 novels in all, plus a history of the nascent U. S. Navy in which he served. These are all available at the site, as are 450+ scholarly articles and some famous graphic images, such as the painters in the painting who are painting the paintings on the walls, in a work painted by friend of the family Samuel F.B. Morse, a prolific and very well-known painter who also invented the telegraph.

Samuel F.B. Morse, Gallery of the Louvre

Audience

The audience for this blog post is the beginning to intermediate Flare user contemplating a web makeover. The post is heavily illustrated, and we do a necessarily brief dive into the world of design and layout.

The audience for the website consists of literary researchers who use the site’s hundreds of scholarly articles to investigate the life and writings of James Fenimore Cooper and his daughter Susan.

From Flare Project to Active Website

A refresher: Flare outputs finished HTML files from its XHTML base with conditions, variables, and other text modifiers resolved. The JavaScript, CSS, and HTML output files generated when you build run a (usually limited) version of a website as browser-based Help. Just direct your project output to index.htm to create a website from these same materials.

Open your HTML5 target file.
In the “Output File” text box, enter index.htm.

3. Save and build the project.

4. Upload the output to the web, in your public_html folder. It’ll look something like this:

5. You can safely delete index_CSH.htm (used only in context-sensitive Help) and <file>.mclog, a text log file.

6. The index file will contain something like this when viewed in a text editor:

<!DOCTYPE html>

<head>

</script>

</script>

</script>

</script>

</script>

</head>

<body>

</body>

</html>

NOTES: Mozilla Developer Network says:

“Robots.txt is a file placed in the root directory of a website that instructs web crawlers on which pages or files they are allowed to crawl and index. It essentially controls the access of crawlers to different parts of a website. 

…

On the other hand, a sitemap.xml file is used to provide search engines with a structured list of pages on a website that the site owner wants to be indexed. This file helps search engine crawlers discover and understand the organization of a website's content, making it easier for them to crawl and index all relevant pages.”

However, neither file is required to make the website run; it just runs much better and faster.

History of the Cooper Website

The forthcoming website site was announced with excitement in July, 2000:

The website and the Cooper Society itself would not have existed if not for the efforts of the late Hugh Cooke MacDougall, a career diplomat in the U.S. Foreign Service who came home to retire at Cooperstown, NY. Hugh taught himself HTML 4.

Hugh MacDougall, webmaster #1

I dedicated a section of the website to him
https://jfcoopersociety.org/content/01-jfcs/hugh.htm.

How I Landed the Project

I had been searching for a contemporary showcase because the corporate projects I create are usually locked down “under NDA” or are otherwise inaccessible to unauthorized users, AKA the public at large. I’ve also been a Poe scholar since 1975 and am working out my theories on what he’s up to in his hoax works at a self-published site, www.howtoreadpoe.com. I’m active in literary forums and struck up an online friendship with the English department chair at the University of Northwestern, St. Paul. Steve Harthorn is currently also executive director of publications at the James Fenimore Cooper Society. Who’s maintaining your site? I asked one day. Alas, no one since Hugh MacDougall died a few years ago. We’ve been updating some files in cPanel, but that’s about it.

Uh-oh.

It was a long sales cycle. Literary societies are just as cautious as depicted in old movies. The main concern was that Flare once used would require investment in a Flare subscription if we were to part ways. I create a Clean XHTML project periodically, which partially assuages their worry, and I’m not using any tricks that are Flare-specific and essential to the project.

In the end, it was the sample projects that I could whip up quickly in Flare that convinced the board. I sent these miniature websites out as zip files via Steve, to whom I would report. One member said that they were “almost too good to be true.” This was by plan. I had followed my own advice ( https://www.madcapsoftware.com/blog/how-to-succeed-at-madcap-flare-consulting) and used just a few files, but absolutely perfect files, for the samples. Plus, I volunteered to work for free, estimating five weeks to complete the conversion. Ha! That five soon stretched into 15 weeks.

Proposal

I developed a minimal proposal for the board’s approval, which went like this:

Date

January 26, 2023

The Objective

Adam Charles Consulting, LLC proposes to provide the services documented herein to support The James Fenimore Cooper Society in achieving its goals of

Website modernization

Searchability improvements

Better manageability and tracking of documentation projects

The Solution

Re-architect the complete documentation system for best usability

Upgrade the existing user interface to a modern design

Convert HTML4 files to XHTML format

Perform unit testing and system testing of the documentation build process

Maintain the website jfcoopersociety.org for a period of 5 years from the date of proposal acceptance, or until February 1, 2028

Provide monthly backups in Clean XHTML format to ensure compatible source for any authoring tool (“future proofing”)

The board accepted, and once the new site was launched, coughed up some actual funds for me—a pleasant four-figure surprise, proof yet again that I’ve never gotten so much in return as when I offered advice or work for free.

Persistence

I never gave up. For example, I’m still pushing Steve to release more graphics for posting.

Project Communications

The most important part of this or any project is communication with stakeholders (I’m tempted to add “early and often”). In this case the stakeholders were the society board and Steve Harthorn, Corresponding Secretary and Executive Director of Publications, to whom I would report. The end users/members? Absolutely silent. I mined Steve for as much information as I could about our readers but did not create a formal description of the persona. Although the “general reader” is sought, almost all users will be academics, on the upper end of the age range and not necessarily comfortable with computers.

I decided to include short, silent videos demonstrating the site’s features.

Emails

Email exchanges were a little chatty and more personal in nature, as Steve and I built a relationship. Volumes have been written on how to handle clients, but anticipating potential roadblocks is always the goal; smooth and steady. Transmittal emails for status reports (spreadsheets and Word files) were strictly business.

Spreadsheets

I created simple weekly spreadsheets to track progress by exporting from the View > File List spreadsheet option. It really wasn’t necessary for Steve to see all these, but of course I needed my own real-time records. Copies went to the website’s record-keeping folder for permanent storage.

Mid-stage spreadsheet of project progress

Announcements

A month before the expected launch date, we sent out a detailed description of what to expect. One week before launch, we repeated the emails.

Part of announcement PDF

I used a friendly, informal approach in the PDF, with a “cute” pointing finger graphic and plenty of white space.

Status Reports

Nothing super-detailed, just the facts:

Cooper Website

July 2023

Usage Statistics

See website webtrends directory for reports.

Updates

Continued proofing updates

Added a book mention for Keat

Changed body font to Adobe Garamond

Added search filtering and updated Help text on how to use it

Outages

Temporary account suspension approx. 24-48 hours due to billing snafu; resolved

Strategizing

Where to begin? A thoroughly deep dive into the site and its hundreds of files was in order. Problem 1: figuring out the navigation. This would be more difficult than expected.

A note on strategy: it’s okay to change strategies once you get into the files. In fact, it will be hard to avoid, because you’ll be encountering surprises all the time. Pull back and reassess from time to time on a scheduled basis. It will most likely save you time and effort.

Documenting the Site Architecture

How do you get a handle on a multi-thousand-page project like this? Document exactly the place from which you’re starting.

Old vs. New Navigation

Original home page

The old design seems logical, at least at first glance. Not a bad try for 2000 A. D. and Microsoft Paint. The designer is trying for balance here, but not all links are to materials at the same level; they are represented in a flattened hierarchy. Much better would have been this “site outline” found in the “introduction” folder:

Linking without JavaScript in a flat hierarchy

A mobile view (in DevTools simulator)

Unfortunately, running the site on a smartphone was never contemplated. This screen shot shows that the identifying information was placed far too low to ever be seen without scrolling; I used the screen simulator in Chrome DevTools.

DevTools in Chrome

Try experimenting with DevTools options to make real-time changes to the browser’s representation of a web page. For example, type in different font families and/or weights and refresh the page rather than rebuilding your project and uploading to see the effects. Note that you can preview in multiple simulated resolutions―much faster than recompiling or switching to another page.

CSS Scan

You may find CSS Scan (https://getcssscan.com/) more user-friendly than free browser tools. Hover the mouse over an area of interest and you’ll see a list of attributes. When you find something worth saving, click the mouse and all the information you see is copied to the Clipboard, available for pasting and editing in your CSS.

Mapping the Site: Decomposition Diagrams

You’ve seen organizational charts before; the levels are shown as bubbles expanded downward to show constituent parts; higher-level bubbles are said to be “decomposed,” i.e., broken down.

Abstracting a site to me means modeling with a diagrammer. We first create an accurate model of the current structure, beat the model up in a thousand different ways, then instantiate the finished creation as a project/website. Some authors recommend spending up to 80% of project time on modeling. Try to anticipate every occurrence―what if x is missing, for example? What’s your contingency plan?

It is infinitely easier to change a model than to hack and slash existing files first. However, your model won’t be precise at first; don’t worry that you didn’t catch everything but do scan the original contents again for implications.

I had been using another, less robust diagrammer, but Nita Beck’s article on MindManager made me give it a try. Unfortunately, Nita has retired, and her site is now closed, but you can visit the MindJet site directly: https://www.mindmanager.com/en/. This tool can be linked to Microsoft Office and Project, and can serve as a very robust project backbone in itself. It’s a question of emphasis.

As you see, the map image can become quite large; exports are lengthy at times, but you can export and import to/from Word, which is a giant boon. Diagram your site; export as Word .docx; edit (or not); import into Flare. The file can also be exported as clickable but unlinked HTML. Boom!

MindManager map of old website shows 15 entry points in an apparently non-hierarchical structure―all entries have equal “weight.”

MindManager map of new website shows entry points reduced to five.

Visit Part 2 as we dive into the website design overview.

View Part 2

About the Author

Jack DeLand

Jack DeLand has delivered Help projects and/or Help authoring training to AT&T, Bayer, BDO, Blue Cross Blue Shield, Blue Sky Software, Cargill, Dell, Delta Dental, Deloitte, Dupont, Exxon, Ford, Gehry Technologies, GM, Harland Clarke, Hewlett Packard, Information Mapping Europe, LA Times, Lucent Technologies, Meteorcomm, Microsoft, Motorola, NCR, Nestlé GLOBE, Raymond James, SAP, Silicon Valley Bank, Sybase, Symantec, Texas Instruments, Thomson Reuters, Unisys, Verodin, and Western Electric, but his abiding interest remains the hoax works of Edgar Allan Poe. These are examined in depth at an evolving scholarly website, www.howtoreadpoe.com. He chooses to specialize solely in Flare development.