[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [dita-adoption-help] DHTG - Topics to be covered
Hi All... Just pushing this thread out there again .. I don't think there were any comments on my suggestions. I'm happy to do the initial update to the topics and create any stub topics for content to be written. The main two points of this thread are .. 1) Suggested top level re-re-organization of the DHTG is .. - Introduction - Help Delivery Technologies - Help Development Tools - Help Development Techniques - Resources Basically just creates a new "chapter" titled "Help Development Techniques" that is the collection point for information that may be common to multiple tools. 2) We should avoid writing topics that cover generating a specific type of help from a specific tool. In general, the process for generating all types of help from any given tool is the same .. you just select a new target type for the project. When talking about a tool we should focus on providing tips/information on things that may not be readily apparent (like when importing DITA into RoboHelp, you can't use OT 1.5, must be OT 1.4), as well as information that might be helpful for someone trying to decide which tool to use (like the list of Help types each tool can generate). It doesn't seem like we should be duplicating the tool's own documentation. The only place that we may want to provide more detailed information is for OT plugins, since there may be very little useful documentation on a given Help output type. It may be that the documentation we develop will/should eventually end up in the official OT documentation .. ? Cheers, ...scott Scott Prentice wrote: > And .. > > Regarding the topics we create for "Help Development Tools" .. how > about if we just use the tool name as the title. For example, the new > topics that Tony has identified would be .. > > * Plus Plug-ins (I assume this is an OT plugin, so it would fall under > the DITA-OT section) > * Creating Microsoft Help 3 Content (if this is not specific to a > tool, it might be in the Technologies or the Techniques section?) > * MadCap Flare > * A Help API for Web-based User Assistance (probably in the Techniques > section) > * Adobe RoboHelp > * XMLMind ditac > * Omsys DITA2Go > - Quadralay ePublisher > - JustSystems XMetaL > > Each tool-specific topic/group should probably describe how you get > your DITA topics into the tool (some are more obvious than others), > then describe the general process for generating Help from that tool. > In general, it's probably going to be the same process for all Help > formats (creating AIR Help from RoboHelp is very similar to creating > WebHelp, etc.). If there are format specific issues, we should list > them .. but I think we want to avoid duplicating the product's own > documentation on these formats. Let's just give people the general > idea, and perhaps some examples. > > ...scott > > > > Scott Prentice wrote: >> Hi Tony... >> >> Thanks for doing this. We also need a topic on .. "Using Quadralay >> ePublisher to Publish to Help Formats". >> >> I'm looking again at the current layout for the DHTG, and it still >> doesn't feel quite right. >> >> At the top level we've got .. >> >> - Introduction >> - Help Delivery Technologies >> - Help Development Tools and Techniques >> - Resources >> >> Introduction looks fine, general introductory info and such .. and >> Resources seems fine with additional info that doesn't fit elsewhere. >> The topics currently in the two main sections doesn't seem like >> there's a clear enough reason for being there (yes .. I'm the one who >> set this structure up). >> >> The Help Delivery Technologies section seems like it should have no >> tool-specific information, just a listing and description of the >> actual Help formats that we discuss. These topics should be >> completely tool-neutral, and just provide a general description of >> each format, and its use (perhaps pros/cons), with a list of tools >> that can be used to create this format. This section would only be >> updated to add new formats and links to tools that support those >> formats (once it's been written, of course). >> >> The Help Development Tools and Techniques section is where the >> tool-specific info should be. There would be a new topic (or group of >> topics) for each tool/technique. Currently, this section contains >> sub-sections for a number of tools, followed by a sub-section called >> "Help Development Techniques" .. this contains topics that discuss >> methods for handling HTML/CSS that applies to many of the Help >> formats. Should this sub-section be moved into it's own top-level >> section so we end up with the following structure? .. >> >> - Introduction >> - Help Delivery Technologies >> - Help Development Tools >> - Help Development Techniques >> - Resources >> >> In general, I'm thinking that we just need to move a number of topics >> from the Help Delivery Technologies section into the Help Development >> Tools section. The following topics are really about "tools" not Help >> delivery technologies .. >> >> - Leximation AIR Help plugin >> - Eclipse Help (the second topic with this name) >> - CSHelp Plug-in >> - Eclipse_CSH Plug-in for Dynamic Context-Sensitive Help >> - Context-Sensitive Help Using the Enhanced HTML (htmlhelp2) Plug-In >> - Context-Sensitive HTML Help Using the The DITA Open Toolkit >> >> Anything that assumes that the user is working directly with the >> DITA-OT, that "tool" would be under the "DITA Open Toolkit" sub-head >> (all of the above fit into this category), and if you're working with >> another tool/utility, that tool would be the heading (even if that >> tool uses the OT under to hood). >> >> I think this will make it easier in the long run to add new topics >> for new tools as they become available. >> >> Does this all make sense, and seem like a reasonable approach? In my >> mind this was what I had intended when I reorged this the last time, >> but when I look at the current structure, it's not what I would have >> expected. >> >> Talk to y'all later today. >> >> Thanks, >> >> ...scott >> >> >> Tony Self wrote: >>> Greetings, colleagues! >>> >>> I have created the shell of a "sign-up" page at: >>> >>> http://wiki.oasis-open.org/dita-adoption/DITA_Help_Technologies_Guide_Alloca >>> >>> tion >>> >>> where volunteers can put their names down to write a not currently >>> covered >>> topic for the DITA Help Technologies Guide. >>> So far, I have figured out that we need additional topics on: >>> >>> * Using the Plus Plug-ins >>> * Creating Microsoft Help 3 Content >>> * Creating WebHelp with MadCap Flare >>> * A Help API for Web-based User Assistance >>> * Creating Adobe AIR Help with RoboHelp >>> * Using ditac to Publish to Help Formats >>> * Using DITA2Go to Publish to Help Formats >>> >>> Can anyone think of any other topics that we need to add? If so, >>> could you >>> please e-mail the list with your suggestion, or else update the >>> table in the >>> Wiki? >>> >>> If you are able to write one or more of these topics, could you >>> please put >>> your name in the corresponding Volunteer column, so that we don't >>> have any >>> duplication of effort. >>> >>> I hope to chat more about this at this afternoon's meeting. >>> >>> Cheers >>> >>> Tony Self >>> >>> >>> --------------------------------------------------------------------- >>> To unsubscribe from this mail list, you must leave the OASIS TC that >>> generates this mail. Follow this link to all your TCs in OASIS at: >>> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php >>> >>> >> >> --------------------------------------------------------------------- >> To unsubscribe from this mail list, you must leave the OASIS TC that >> generates this mail. Follow this link to all your TCs in OASIS at: >> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php >> > > --------------------------------------------------------------------- > To unsubscribe from this mail list, you must leave the OASIS TC that > generates this mail. Follow this link to all your TCs in OASIS at: > https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php >
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]