On Fri, Apr 26, 2013 at 12:34 PM, Dennis E. Hamilton <orc...@apache.org> wrote: > I favor the idea of rethinking the Help system. I also think that it needs > to be decoupled as much as possible from the AOO 4 staging, doing the least > that works for AOO 4.0. The mechanism should allow incremental upgrading and > evolution that does not require synchronization with releases in the AOO 4 > line. > > I for one, prefer the option of downloading and installing embedded help, to > provide materials that can be accessed when connectivity is inadequate. > Embedded help should not block movement to on-line help for additional and > potentially-later material though. > > DANGER, DANGER: Home brew help systems tend to never be finished, the content > tends to never be full migrated and consistently maintained. It would be > useful to use something that is as decoupled as possible from the product > builds while providing some well-defined bridge from contextual-help > triggers. A system with established endurance and open-source compatibility > would be ideal. Perhaps it is time to look at DITA and well-established > help-authoring aids. Important touch-points will be multi-lingual authoring, > accessibility, and modularity of creation. >
I think that when Sun made their help system for OOo there was no good alternative around. So if they wanted a cross-platform solution it had to be a homebrew. But, as you note, that has costs. No doubt if we were doing something from scratch we'd use something like DITA, well-supported by tools. The advantage of DITA is we get the content into one standard format, and then using the open source DITA Open Toolkit (under Apache License) we can generate help in many useful formats, such as: XHTML PDF ODT Eclipse Help TocJS HTML Help Java Help Eclipse Content Word RTF Docbook Troff See: http://dita-ot.sourceforge.net/1.7/ DITA also makes it easier to "slice & dice" the content, so we can maximize reuse. For example, I bet a list of spreadsheet functions and their parameters shows up in our help and our user guides. But this is duplicate content in two different systems. With DITA you could unify this content in one place, but still generate subsets of it into help format or PDF for download. -Rob > - Dennis > > THINKING OUT LOUD > > I notice that our LibreOffice cousins have separated out the embedded help as > an independent download. That seems to be an appropriate way to shrink the > main install. > > These days, Microsoft Visual Studio Express Editions work in similar ways, > although downloading the embedded help is an option in the Help Menu. This > is pretty valuable because there are so many help topics and developer > components that may or may not be of interest. > > Because of download difficulties, different client system capacities, the > need to have media-installed versions, etc., it would be great to have some > user-controllable flexibility in this area. There is also reason for > separate modularization to deal with localization and the availability of > content in different languages that is not in lock-step with each release and > binary distribution. > > I *don't* fancy embedded help that blocks access to on-line help. These > should not be exclusive choices. There needs to be more flexibility in that > area. > > There might even need to be more granularity around help as well. It could > be a valuable accompaniment for documentation, study guides, tutorials, and > classroom usage, including provision of exercises. These days, the Help menu > is often offered as a way to report troubles, access communities (forums and > wikis), etc. > > Another important consideration with regard to embedded/on-line help has to > do with version dependencies and having information that is correct for the > product being used. That is going to be important depending on the feature > roll-out for the AOO 4 line. It needs some way not to interfere with those > who have a requirement for such information on the AOO 3 line and older. > > Going to a new Help system is always tricky. Using an HTML-based help model > has great appeal because it means that embedded and on-line help can rely on > similar authoring. It also helps having embedded help work with a plug-in > that can obtain independent updates of content, even multi-lingual content. > This is a different version-consistency issue. > > It seems necessary to start simply and stay simple. Use of standard formats > that don't require much documentation is important. The on-ramp for authors > and translators needs to be very low friction. For the coordination of > product, embedded help, and on-line help content and providing contextual > help, there might be a valuable case for use of RDF metadata [;<) ... > eventually. > > PS: In 2000, I earned a certificate for help authoring. It was with an eye > to a new help format that Microsoft was proposing to introduce beyond its > HTML Help system. Didn't happen and I found other things to do in the > meantime. > > PPS: Commercial Help authoring systems are very pricey and very silo-like. > It would be great to have something better, simpler, and easier to integrate > while avoiding diversion into a costly home-brew effort. > > -----Original Message----- > From: Jürgen Schmidt [mailto:jogischm...@gmail.com] > Sent: Friday, April 26, 2013 04:18 > To: dev@openoffice.apache.org > Subject: INFO: OpenOffice help authoring > > Hi, > > I tried to find some info (thanks to Ariel for some additional pointers) > about our help format and the help authoring tooling. If somebody has > the time and interest to dive deeper in this material here are the > pointers I have so far. > > http://www.openoffice.org/documentation/online_help/ > > http://www.openoffice.org/documentation/online_help/OOo2HelpAuthoring.pdf > > As mentioned earlier I have also investigated in the helpauthoring > extension that is probably useful to maintain and/or create help files. > > A version (including the template) can be found under > http://people.apache.org/~jsc/test/helpauthoring.oxt > > > Nevertheless should we start thinking about a replacement and using a > real online help as preferred solution. And an offline help version as > optional download... Something like that, it would reduce the install > package a lot > > > Juergen > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@openoffice.apache.org > For additional commands, e-mail: dev-h...@openoffice.apache.org > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@openoffice.apache.org > For additional commands, e-mail: dev-h...@openoffice.apache.org > --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@openoffice.apache.org For additional commands, e-mail: dev-h...@openoffice.apache.org
