[Framers] [WTF ramemaker] Best Practices for HTML Online help
Art Campbell
art.campbell at gmail.com
Sat May 18 06:50:48 PDT 2019
So, based on Caroline's and Robert's info and contributions, and thoughts
from everyone else, I'm going to reccommend that our starting point for a
coding spec be the Frame-to-RoboHelp workflow, with us, doc, retaining
control of the map file. TBD is how the coders would inform us / update
with new hooks on the code side.
Does that sound reasonable to y'all? After we do a couple projects, we will
revisit and tune.
Art Campbell
art.campbell at gmail.com
"... In my opinion, there's nothing in this world beats a '52 Vincent and
a redheaded girl." -- Richard Thompson
No disclaimers apply.
DoD 358
On Thu, May 16, 2019 at 1:24 PM Robert Lauriston <robert at lauriston.com>
wrote:
> The Using FrameMaker topic says it creates a "sample" map file which
> you can use "as a reference to create your map file." What does that
> mean?
>
>
> https://help.adobe.com/en_US/framemaker/2019/using/using-framemaker-2019/WS2d2a17056e2191986533fc06144fd9afdc4-8000.html
>
> It doesn't sound like it handles updates the way RoboHelp does.
>
> On Thu, May 16, 2019 at 1:02 AM Caroline Tabach
> <caroline.tabach at gmail.com> wrote:
> >
> > Hi
> >
> > In the link you sent, it says that the FrameMaker publish procedure
> creates
> > a sample h file.
> >
> > And it does indeed.
> >
> > Unfortunately, as you noted, creating HTML 5 help is not documented well
> > enough in the Frame help.
> >
> >
> >
> >
> > Caroline Tabach
> >
> > On Wed, 15 May 2019, 22:20 Robert Lauriston, <robert at lauriston.com>
> wrote:
> >
> > > Caroline said via email that FrameMaker does generate the map file
> > > automatically. Is that true? The documentation explicitly says you
> > > must create it with a text editor:
> > >
> > >
> > >
> https://help.adobe.com/en_US/framemaker/2019/using/using-framemaker-2019/WS2d2a17056e2191986533fc06144fd9afdc4-8000.html
> > >
> > > On Tue, May 14, 2019 at 12:13 PM Robert Lauriston <
> robert at lauriston.com>
> > > wrote:
> > > >
> > > > Sure, it's technically possible, but automatically generating the map
> > > > file is a basic feature of help authoring tools. Doing it manually in
> > > > a text editor invites human error.
> > > >
> > > > The FrameMaker doc itself points to the RoboHelp "Information for
> > > > Developers" section. That's the correct way to write help calls in
> > > > applications.
> > > >
> > > > The help calls you described in
> > > > https://forums.adobe.com/thread/2314670 are a kludge and I would
> > > > strongly recommend not doing that. At a previous job I had to rewrite
> > > > hundreds of help calls in the source code because developers used a
> > > > similar kludge, which by the time I took over the project a few years
> > > > later had resulted in many broken links.
> > > >
> > > > On Tue, May 14, 2019 at 11:48 AM Caroline Tabach
> > > > <caroline.tabach at gmail.com> wrote:
> > > > >
> > > > > I have made context sensitive help without RoboHelp. ...
> > > > >
> > > > > On Tue, 14 May 2019, 20:58 Robert Lauriston, <robert at lauriston.com
> >
> > > wrote:
> > > > >
> > > > > > Looks like having both FrameMaker and RoboHelp (i.e. Adobe
> Technical
> > > > > > Communication Suite) is essential for publishing
> context-sensitive
> > > > > > help.
> > > > > >
> > > > > > RoboHelp can generate the map file from the TopicAlias markers:
> > > > > >
> > > > > >
> > > > > >
> > >
> https://help.adobe.com/en_US/robohelp/2017/robohtml/#t=book%2Frob_createhelp_ch%2FManaging_map_files-.htm%23TOC_Export_a_map_filebc-3&rhtocid=_10_2_1_2
> > > > > >
> > > > > > FrameMaker multi-channel publishing requires you to maintain the
> map
> > > > > > file manually in a text editor, which is insane:
> > > > > >
> > > > > >
> > > > > >
> > >
> https://help.adobe.com/en_US/framemaker/2019/using/using-framemaker-2019/WS2d2a17056e2191986533fc06144fd9afdc4-8000.html
> > > > > >
> > > > > > On Tue, May 14, 2019 at 9:58 AM Robert Lauriston <
> > > robert at lauriston.com>
> > > > > > wrote:
> > > > > > >
> > > > > > > Since you're posting this on the Framers list, I presume you're
> > > using
> > > > > > > FrameMaker.
> > > > > > >
> > > > > > > Its "multi-channel publishing" feature is a subset of
> RoboHelp. You
> > > > > > > probably want to choose Responsive HTML. Do not choose
> Microsoft
> > > HTML
> > > > > > > Help.
> > > > > > >
> > > > > > > Alternatively, link the FrameMaker source to RoboHelp, and
> you'll
> > > have
> > > > > > > the full RoboHelp feature set. In that case, you might choose
> > > WebHelp
> > > > > > > over Responsive HTML. Look at both.
> > > > > > >
> > > > > > > On the FrameMaker side, define the target topics using
> TopicAlias
> > > > > > > markers. That's covered in the FrameMaker user guide.
> > > > > > >
> > > > > > > On the app side, you can find detailed information on CSH
> calls in
> > > the
> > > > > > > "Information for Developers" section of "Context-sensitive
> help"
> > > > > > > chapger of the RoboHelp user guide.
> > > > > > >
> > > > > > >
> > > > > >
> > >
> https://help.adobe.com/en_US/robohelp/2017/robohtml/#t=book%2Frob_createhelp_ch%2FInformation_for_developers-.htm
> > > > > > >
> > > > > > > *** You want to create and maintain the map file and provide
> it to
> > > the
> > > > > > > developers, not vice-versa. ***
> > > > > > >
> > > > > > > You do not need a separate target topic for every application
> > > context.
> > > > > > > Many application contexts can point to the same help topic.
> > > > > > >
> > > > > > > Be sure that the developers implement a default help topic to
> open
> > > > > > > when a context is unmapped or the map is wrong.
> > > > > > >
> > > > > > > On Tue, May 14, 2019 at 7:44 AM Art Campbell <
> > > art.campbell at gmail.com>
> > > > > > wrote:
> > > > > > > >
> > > > > > > > My company is developing a new browser-based software package
> > > that is
> > > > > > specced to include screen-level context sensitive help.
> > > > > > > >
> > > > > > > > The coders haven't done this before and are asking for
> > > > > > help/assistance/advice on developing the coding standard for this
> > > and other
> > > > > > products going forward.
> > > > > > > >
> > > > > > > > I'm thinking the basics are the basics -- a call in the
> program
> > > goes
> > > > > > to a mapping table that invokes the HTML help screen in a new
> > > tab/window or
> > > > > > a popup.
> > > > > > > >
> > > > > > > > What I'm looking for feedback / ideas on are a good method to
> > > call
> > > > > > Help from the application (icon/keystroke/widget), and any Best
> > > Practices
> > > > > > that people are already using, either on the coding or
> information
> > > > > > development side.
> > > _______________________________________________
> > >
> > > This message is from the Framers mailing list
> > >
> > > Send messages to framers at lists.frameusers.com
> > > Visit the list's homepage at http://www.frameusers.com
> > > Archives located at
> > > http://www.mail-archive.com/framers%40lists.frameusers.com/
> > > Subscribe and unsubscribe at
> > > http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
> > > Send administrative questions to listadmin at frameusers.com
> > >
> > _______________________________________________
> >
> > This message is from the Framers mailing list
> >
> > Send messages to framers at lists.frameusers.com
> > Visit the list's homepage at http://www.frameusers.com
> > Archives located at
> http://www.mail-archive.com/framers%40lists.frameusers.com/
> > Subscribe and unsubscribe at
> http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
> > Send administrative questions to listadmin at frameusers.com
> _______________________________________________
>
> This message is from the Framers mailing list
>
> Send messages to framers at lists.frameusers.com
> Visit the list's homepage at http://www.frameusers.com
> Archives located at
> http://www.mail-archive.com/framers%40lists.frameusers.com/
> Subscribe and unsubscribe at
> http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
> Send administrative questions to listadmin at frameusers.com
>
More information about the Framers
mailing list