Hello (FM 11 Documentation)

[David Artman]

-------- Original Message --------
From: Robert Lauriston <robert at lauriston.com>

...
Things like that. The current state of the FrameMaker docs is the
result of them being updated with new features release after release.
You should rewrite from scratch with a task-oriented focus.

------
While I'm inclined to agree--and as I acknowledge that 'cobblers wear no
shoes' and we'll never have perfect documentation about documenting with
FM--it is no mean feat to address every "task" that one might attempt in
FM. I'm not sure how I would begin, and I've used if for quite a while
(though not so long as many here).

What I think gives more "bang for the buck"--again, assuming we can't
have it all--is doing more and better work on the provided templates.

I should be able to open a template and:
* See every style applied somewhere, in "real" applications (with lorum,
if necessary) not just a word or two so you can click it, and DEFINITELY
not blank.
* See usage _explained_ when a non-obvious technique is employed (e.g.,
2pt height, -2pt above anchor lines; resetting numbering on list intro
headings NOT on stupid "List 1/A" styles!). [Yes, I know: it's high time
I insisted upon clients Structured FM!]
* See even more info on the Reference pages--would it kill you to
explain the all of the building blocks for Index or TOC tagging in a
text box on those Ref pages?!
* Compare and contrast with other templates with the same deliverables
goals, but different major style elements (e.g., step-level indentation,
which calls for TONS more List styles; or
Chapter-Page(-Figure/-Table/-etc) numbering which calls for use of
BOOK-level tools and/or Running H/Fs)

And so forth: A DITA project that I can immediately deploy, if I'm none
too picky about appearance yet. Maybe a structured application or five
that actually DO what 90% of all software and hardware companies need
(HTML Help, PDF-for-print, PDF-for-screen, ePub).

And I think you can save yourself the effort of delivering "business"
templates anymore, which will free up development time for those really
awesome, thorough, real-world-case templates. I mean, does anyone really
use FM for that, with Open/Libre/MSOffice totally dominating that
content generation space?

(TL;DR:)
I would rather learn by reading explications of actual, working template
files that are already 80% of the way to being what I need for any
publication, than reading "empty" instructions in a user guide. And when
I'm ready to use those working template files to build up content,
Ctrl+A, Delete removes all of the "learning tools" and samples, leaving
only clean pages (with H/Fs). And I'm not having to add fifty styles to
deal with real-world cases going forward.

David