Community
Participate
Working Groups
Implement new help TOC editor. * Implement model * Implement UI * Implement functionality User Assistance Tooling: TOC Management Please see Bug # 146988
CC'ing UA Team to keep them in the loop.
We have a mock-up for something we envision as a "my help" TOC that would actually allow an end-user to create their own personalized TOC. We know from feedback that customers really want to customize the docs. So, there would be the regular TOC, built up by doc teams and shipped as default with a product, but then the TOC would have a divider. Below the divider would be an area where a user could drag and drop nodes from default TOC to build up their own TOC. They could add folders, subfolders, rename topics in the TOC, mark them with stars, etc. When a doc team is preparing their product, they could use this my help mechanism to build their default TOC that they ship.
Hi Seth, Could you elaborate a bit on comment 2 and/or provide an illustrative picture? I do not quite understand the use case. We are working on the TOC editor right now, so now is a good time to come up with a vision on what the editor should and should not do.
Seth, I am sure this comes as part of the larger push for more wiki-like behaviour of documentation where users can edit/modify. However, when it comes to TOC, wouldn't enhancing bookmarks work in a similar way? You can start with a fixed TOC and build up a structure with folders and bookmarks where you can also edit the name of the bookmark (of course, this is a discussion for the UA inbox, not PDE). As far as PDE is concerned, are you implying that the direct editing support for the TOCs would make the TOC editor redundant? If so, I tend to disagree. Your scenario implies a closed product situation where the complete TOC is known. One of the major strenghts of Eclipse Help is that TOC is built up from individual contributions that are woven together at runtime. The upcoming editor was meant to assist plug-in developers to create these TOC contributions, not edit the final 'mother TOC'.
Created attachment 72658 [details] Mockup screenshot of a dynamic Help TOC-building UI
The Eclipse Help does not weave together the TOCs dynamically. The TOC still has to be managed by an information architect. In fact, the Eclipse Help TOC design has many flaws which make this very difficult and unpredictable. When we deliver a product with literally hundreds of help plug-ins whose TOCs have all been architected in different ways, with some being designed for a primary="true" scenario, and others being designed as sub-TOCs, a master TOC does have to be carefully crafted for each offering. Otherwise, you get a jumbled mess of unordered, disorganized, and inequal TOC contributions coming from dozens of different contributors. I would argue that the use-case you describe is less crucial than the ones that I describe. It is very easy for a help plug-in contributor to construct a single entry in the TOC. We have authoring tools that do this automatically for us. On the other hand, it becomes increasingly complex to organize and manage 30 or 40 help TOCs, which don't all know about each other, to get proper linking and anchoring of TOCs to build up a logical help TOC hierarchy. In a highly componentized product install stack, only the information architect knows which Help plug-ins are coming in, and they need to be manually accounted for. So, a UI tool to create the master TOC from all of the varied contributions would be useful in at least the following scenarios: 1. For a product's information architect to prepare a final master TOC before shipping the product. 2. For an end user who wants to configure a custom master help TOC. We know that our users want to customize. Our vision could be considered a beefed up bookmarking system, but it involves dragging and dropping of entire nodes or single topics into a separate pane in the Help TOC. I've attached my mockup to illustrate. (Please see the attached gif) A similar model is used in the Welcome. We use the Customize Layout button to control the ordering, placement, and inclusion of all of the Welcome contributions from various sources, then we save the configuration and ship it as the default. Sorry for the long comment. I look forward to more discussion and answering any questions that you have about Help content design and architecture.
Seth, I see your point. You put an emphasis on releng-time customization of the product that can be saved and shipped with it (as in Welcome). Note though that it falls appart the moment you add another feature to that product. In the case of Eclipse release trains (Europa) people are starting from the platform, then adding various features they need for their work. There are dozens and dozens of these features and they can all be added in the random order. The idea that the user can reorganize the master TOC after installing these features is an intriguing one, I only wonder if enough of them will bother (similar to the ability to change colors of your OS skin). It still does not absolve us from the requirement to provide ways to get the best possible default. Wassim, please consult Curtis regarding the support for categories. He added this feature in 3.2 (I think) allowing individual primary TOCs to be added into these caregories in the effort to reduce the randomness of the master TOC. See if we can surface this in the TOC editor (although it would require identifying the 'product' plug-in and reading/writing files there).
Sounds like we have 3 use cases: 1. Plug-in developer writes a help table of contents entry for their plug-in (what Noam is currently doing) 2. Product information developer organizes contributions into a coherent way. 3. User organizes their custom toc / structured bookmarks. Seeing as #3 should happen within the help system itself, not in a PDE editor, this is outside the scope of this enhancement (should be a separate one). Agree?
Yes. We should proceed with 1. and see if we can address 2. as well. Tooling for 3. cannot commence before such a function is added to UA anyway.
btw, I figure I would just raise my concern that I don't know anyone but the Eclipse team that actually writes their TOCs by hand. They tend to usually be generated given some input (ie., DocBook or DITA). If this is the case, are we really spending our time wisely here?
I agree that this PDE feature would be of no apparent use to any Help developer that I know of. So, the resource investment should be considered carefully. From a UA perspective, I agree that Curtis's use-cases 2 and 3 are most valuable from this discussion, but are not PDE concerns so should be separate requirements. BTW, is there a plan for UA features for Eclipse 3.4 or 4.0?. I know we've been solicited to provide input, and we have tons of ideas.
Chris, Can you provide statistics/data to back up the claim in comment 10?
I just talked to the wife (since I figured she would be a good source) and she said using DITA to generate TOC files is an IBM standard. There should be no one creating documentation for IBM products who is modifying a TOC by hand. This doesn't really count as a statistic, but I figured I would throw it in for consideration.
Point taken. But big IBM products don't use the Product/RCP editor to build standalone Eclipse products either; yet it's one of our greatest hits. Catering to the small guy is never a waste of time.
I don't think PDE would have a coherent UA tooling story if it did #2 and not #1. That is, for the very common use case of writing help for a plug-in, which everyone needs, it has nothing, but for piecing it together for a product, which not everyone needs (e.g. Europa), it does. Since you already have your own tooling, why not expand that tooling, rather than trying to get PDE to fill the holes and end up with very specific partial tooling, with it's own holes?
Our investment in 1. is modest and addresses open source use cases (all of Europa projects craft TOCs by hand). It is known for a long time that large companies that use DITA have their TOCs generated. Use case 2. is applicable to all cases because TOC categories is an Eclipse concept. UA requirements for 3.4 should be discussed with the UA team outside this enhancement report.
The TOC editor is in, stable, and, dare I say, pretty. I don't think we need to keep this report open any longer.
Agree. (Agree on the pretty part too). Target: 3.4 M1
Now I must try it (to attest the pretty :-).
How do I access this feature? Curious to see how pretty it is.
RE: Comment #20 Use Eclipse Build id >= I20070731-0800 (Ideally 3.4 M1) (1) Double-click on any existing TOC file in the Package Explorer view (e.g. /org.eclipse.pde.doc.user/toc.xml) OR (2) Create a new TOC file using the new TOC file wizard (e.g. File > New > Other > User Assistance > Help Table of Contents)
(In reply to comment #21) > Use Eclipse Build id >= I20070731-0800 (Ideally 3.4 M1) I20070731-0800 has the TOC Editor, but still opens TOCs in a text editor, making it a bit of a headache to actually make use of the editor. From Build I20070807-0010 onwards this doesn't happen. :)
adding noteworthy keyword
