Bugzilla – Full Text Bug Listing
| Summary: | Automated Documentation Generation | ||
|---|---|---|---|
| Product: | z_Archived | Reporter: | Ashish Patel <ashishp> |
| Component: | TPTP | Assignee: | DuWayne Morris <dmorris> |
| Status: | CLOSED WONTFIX | QA Contact: | |
| Severity: | enhancement | ||
| Priority: | P3 | CC: | adn, alarakhi, dale.ollila, paulslau, ruthdaly, scott.schneider |
| Version: | unspecified | Keywords: | helpwanted |
| Target Milestone: | --- | ||
| Hardware: | PC | ||
| OS: | Windows XP | ||
| URL: | http://www.eclipse.org/tptp/groups/Architecture/documents/features/hf_110108.html | ||
| Whiteboard: | |||
|
Description
Ashish Patel
Set the version to 4.2. I will change the target milestone once it is approved for the plan. It might be nice if we can cite corresponding infopop help topics (either by file name or topic). Thus, localizers (i.e. translators) can make sure they are using the correct screen shot. Note: you can bring up the infopop help (or dynamic help) for an active pane by pressing F1. Generating the documentation steps is useful because that's currently a manual test (the "step through" test case). The generated documentation would need to be integrated manually into the existing documentation because we provide more than step-by-step instruction in the documentation, but it would cut down on the amount of manual verification that we need to do in the final iteration test pass. I would like this enhancement to cover generating screen captures as well as HTML documentation. 1. Instead of asking people to manually verify the screen captures in our documentation, we could run a test that would generate all of the screen captures. We would be able to assume that we need to delete all of the existing captures and update them for each release. 2. As Abdullah points out, it would be _AWESOME_ for translation, because currently we have the issue where some screen captures are going out in English when translators don't have the time (or the skills) to reproduce the steps to get the equivalent screen capture. 3. It would be great for consistency because all screen captures would be taken with the same resolution on the same machine. Currently we have a mix of Windows 2000 and XP captures, and the resolution is all over the place. In regards to Ruth's comments: 1. I agree with regenerating screen captures for each release. This is important incase icons, labels, or other GUI elements become present in a new release, as it helps the user to accurately identify what they are doing is correct [ according to the generated documentation ]. 3. Since your output is HTML (or some type of transportable document format) please output graphics using a PNG format - this will help preserve the alpha transparency channels present in high-res GUIs (such as for MACOSX and WindowsXP/Vista). In addition, the file sizes will remain small compared to BMP's but have better quality than JPGs. 3a. You should also stick to a good resolution for the HTML docs (perhaps 800x600) ? Maybe you want to add a feature to change to that resolution before executing the test case too so that all the screen shots are consistent. [ thinking out loud ] We don't have TPTP guidelines on screen captures yet (have to work with Alex, Dale and Abdullah to come up with some guidelines). That said, here's a first pass at a standard (people can comment in this bugzilla on their ideas): a) screen resolution 1024 x 768 b) interlaced GIF file with some maximum size, e.g. 540x540 pixels The idea behind the maximum size is that the screen capture doesn't dominate the topic. That said, I expect that being able to set a maximum pixel size is not a reasonable thing to ask the Auto GUI tool to do. ;o) We could ask people to manually set their screen resolution before running the scripts to generate all of the screen captures. Agreed to (1) allowing the user to set the screen resolution. I think there should be something in the automation UI to set this before the test is started, and then reset the screen resolution after the test finishes. It's convenient for the user not to have to go off into the OS's config and set it, then reset it to something that they like to normally use when the test is done. (2) I still prefer the PNG format over JPG/BMP/GIF for reasons stated previously in this feature. However, it shouldn't be any more work to output to any of these formats if you're using a flexible graphics layer in Java. I think the pixel size of the image should be determined once we actually have some of this feature working so we can see various sizes and decide. I think we're making good progress :D Thanks for everyone's contributions! Just a thought ... what about the idea of generating the steps into a .xml file and then running some sort of a script to generate the .html file from there? 1. Create one 'template' file that contains all information but the steps. 2. The AutoGUI tool could generate the steps & screen captures into another file. 3. Run a script to generate the .html file based on the template file & step file. I'm not sure how we could do this generation step, nor what format the template would need to be in, but this would remove the manual merging of the generated and the hand-crafted docs. I like the idea of having a template. From a technical perspective, I would think there should be a well-defined and approved XML schema for the documentation. When I say "well-defined and approved" I'm thinking of collaboration between TPTP, open-document standards, documentation generators, information development teams, and real products (ie. WebSphere's business integrator), etc. I say this because its not effective to just have a schema designed for one purpose (that is our purpose) alone. Having a schema will allow parties to use XSLT to convert the auto-generated step-by-step instructions into any proprietary format that a vendor may have. Once this conversion is complete you have have an XSL (or some xml-based style sheet) to view the XML-based instructions in any browser. This may remove the need to generate the HTML since most browsers can save the rendered XML as HTML if it has an XSL [ I've done this a couple of times with primitive examples ]. I know that some IBM documenters use the OASIS DITA standard (Darwin Information Typing Architecture) but I don't know if that XML open-source standard would help us: http://xml.coverpages.org/dita.html That said, there was once a feature opened to have TPTP docs converted into DITA format because it was viewed as a better way of creating docs. I returned it as WONTFIX at the time. Description Document: http://www.eclipse.org/tptp/groups/Architecture/documents/features/hf_110108.html proposed to be planned for 4.2 but no resources are available (helpwanted keyword added) Target set to 4.2 helpwanted for 4.3 What exactly are you requesting help for? Are you looking for someone to contribute this entire feature, or provide parts of this functionality? Please elaborate. Here's my view (Christophe can add/correct my response): We won't turn down any help that any contributor can offer (e.g. design, implementation, and even testing). Ideally I would like to design this enhancement and have someone implement it. I will take the time to test and approve the check-in or delay it based on its stability. Some new information to consider as part of this enhancement. (Sorry that it came after the description document was written!) PROPOSAL: I think that instead of generating a screen capture after every step of a test, the test should be editable to control when a screen capture should be taken. DESIGN ISSUES BEHIND THE PROPOSAL 1. I've discovered that it's considered bad for usability to insert too many screen captures in the documentation because that can slow down the user, potentially frustrating them. Apparently most users scan documents for the information that they need to perform a task. If you have many screen captures, say one for each step of a task, that limits the user's ability to scan the documentation quickly. It becomes cumbersome because you have to scroll instead of skimming the page. The guideline that I've heard is that screen captures should be in the documentation only to show the result of a series of steps. This screen capture acts as a summary, providing feedback to the user that they have completed all of the steps correctly so far. For example, look at "Tutorial: Accessing a datapool from a JUnit test (http://help.eclipse.org/help32/topic/org.eclipse.hyades.test.doc.user/samples/saccessdp.htm) -> The screen captures in "Setting up a TPTP test suite" show what the user should see after they have performed a series of steps. In contrast, look at "Profiling a Java application that is external to the workspace" (http://help.eclipse.org/help32/topic/org.eclipse.tptp.platform.agentcontroller.doc.user/tasks/rac/tiacprofileexternal.html) -> The screen capture is not helpful because it demonstrates basic knowledge: step 1 (create) step 2 (select). Most users, even non-technical ones, recognize that a highlighted object is selected. The steps in this topic are few enough and simple enough that they don't need the summary. 2. From another usabilty perspective, in TPTP V4.2 for the first time I had to run accessibility tests on the documentation. There's many rules that the generated documentation would need to follow. I won't clutter this enhancement by enumerating the current list of accessibility rules for documentation because they'll probably change by the time that this enhancement is implemented. However, there's one rule that I think needs to be taken into consideration during the design of this enhancement because it has such a huge impact on usability and maintenance. Every image must have an "alt" attribute. When an image is inserted into a file, the screen reader reads the text of the alt attribute to the blind person because person can't see the image. The text of the alt attribute must accurately describe the image and must make sense in the overall text of the paragraph that is being read to the blind user. 3. From a maintenance perspective, the accessibility test requires that every page that has an image must be listened to by the accessibility tester to ensure that the alt tag is set and makes sense (matches the image). If I remember correctly, it took about five minutes a page on average to listen to a page in its entirety. A file does not need to be retested if it has no changes, but if it is changed then that test must be performed again. I don't have a number for how many pages change during a release (because I never needed to know that information), but for a benchmark let's start with what we have today. I believe that we have about 1600 doc pages in the TPTP doc plug-ins. Assuming 1% change, no new files, and that this enhancement inserted screen captures on every generated page of documentation, then at 5 minutes per page, the "listen" test would take about 13 hours 30 minutes. And that's just one of the accessibility tests for docs. BTW, this test isn't fun. ;o) DETAILED EXPLANATION OF THE PROPOSAL: For the first design issue, my thought would be that the test recording should be editable so that a person who writes a test could identify when to take a screen capture. I don't think that the right moment to take a capture can be automated because it will depend on the content of the test. For the second design issue, again I think that the test recording should be editable so that the user can specify the text of the alt attribute at the same point when they specify "take a screen capture here". Only the user will know what they want to draw the user's attention to in the screen capture. (alt text has to be short, usually around 60 char if I remember correctly. I can check on the length restriction if you want to know for sure what the number is. I _think_ that this limitation was due to the differences between screen readers, but I'd have to verify that.) For the third design issue, being able to choose when a screen capture is taken and being able to set the alt value for that screen capture won't remove the need for listening to the page. It will, however, control the number of screen captures and thus reduce the number of pages that need to be listened to. And there's less chance of finding a problem with the words of the alt text if the user has control over what text is inserted into the generated documentation. Given the additional requirements that I've just identified, I can believe that it's necessary to separate the "screen capture" requirements into a separate enhancement. But I'll leave that up to you. Updating target to future as requested by the PMC. Enhancements are targeted to future if not in plan for the current release. Reassigning to current component lead. Correcting priority since not a 4.5 candidate enhancement (see http://www.eclipse.org/tptp/home/documents/process/development/bugzilla.html). In TPTP 4.5, the AGR was moved from a Technology Preview component to an As-Is component. As-Is components are primarily provided for prior users but imply no support (for example, defects, news group, and mailing lists) or commitment to triage or resolve opened defects. For this defect to be considered, please re-open with an attached patch including code to resolve the symptom and test cases to test the fix. Closing by default since not closed by the originator in the 7+ months since being resolved. Please reopen if the issue is still present in the latest TPTP release or the resolution is not correct. |