Goldenseal accounting software comes with two printed manuals. Our staff started to write them in the 90s, while the programmers were still building C++ code. Often, the manual text was specs for how the app should work.
Physical books are not easy to make. Each manual took more than a person-year to finish. Even the printing process is complicated: pages need to be set up in weird pairs so they’ll come out right when cut and assembled. It took a while to find bindings that lie flat on a desk, and that won’t bunch up.
Support for the the new (yet unnamed) accounting software will be 100% online. Nothing on paper. Books have some advantages, but not enough to be worth the extra time they take. It’s also hard to keep them updated.
The current TurtleSoft site has the print manuals as pdf downloads, and also as web pages. The web version uses text and images from the print version, with hyperlinks added.
This week our staff started to update the online manual to work for the new accounting app. We redid a dozen pages, but soon ran into a snag.
Problem is, when the paper manuals were written, they were the only reference for users. They needed to include everything. Our app does a lot, so it took plenty of text to cover all the details. The books are split into lessons that have a bit of humor, but 400 pages of tech stuff is a lot to get through. Most likely, few people have read it cover to cover.
These days, there is an online Reference Manual with instructions for each window and dialog. Also Special Topics that cover obscure stuff, plus Tech Answers and the Answers button for problems. On top of all that, the web version of the print manual. There are plenty of ways to get help.
The manual pages were just too long and complicated as web pages. We split most of them into a main thread and branches, but that wasn’t enough.
The ideal for “getting started” is an express lane that only covers the very basics. Enough to get anyone up and running in an hour or two. Like, a 20 page booklet with videos. It can always link to pages with more details. That way, users can take their pick: Interstate or scenic route.
Redoing the manuals entirely is a big step that needs thought and design time. Our staff should do it gradually, in parallel with final testing and video making. Maybe it’s what we should put on the main page.
State payrolls, tech answers and special topics are already done, so we moved on to the Reference Manual. It’s 300 web pages, the last big hunk. Some pages are also too big, and need to be split. That makes it slow going. At current pace, it will take into January.
The short-term goal from all this website work is to get a checklist for testing the app. Then we can work through pages in order, and not miss anything. The old manual pages would have done that, but now they are an interconnected web just like the rest of the site.
I’m pretty sure that searching a network and not missing anything is NP-Hard. Similar to the Traveling Sales Rep. You can start at any page, follow a link, follow one of its links, and keep going until you hit something already seen. Then go back one page and follow its next link. Repeat until done. It would be tedious at best on 2000 pages. Maybe one of those billion-year things.
Fortunately, there’s the Answers button. That’s A-Z. It’s how we’ll organize final testing. There still will be some recursion, but not so deep.
The long-term goal: it will be grand to be paid eventually for all the labor that has gone into the new estimating/accounting app. A modern website is a necessary part of actually selling the app to new users.
Dennis Kolva
Programming Director
TurtleSoft.com
