Posted: Tue Dec 16, 2008 11:41 am Post subject: Documenting 3rd-party functionality
I've been in dialogue with the oo-build folk about some of their added functionality in Calc, which will be making its way into NeoOffice v3.
Something that strikes me is that I'm not sure how users get to find out how to use this stuff if there's nothing in the OOo-ported Help about it. For example, the two cool things that I've been playing with are:
i) the ability to toggle the sheet grid lines in the screen display - very useful for presentations, but knowing how to add this functionality to key combos/menu is pretty arcane (the function 'Toggle Grid Lines For Current Sheet' is hidden in the Format category, even though it's actually a UI toggle - even the oo-build folk don't know why they put it there ).
ii) a related issue: they've implemented something similar to what Excel does - when you select a cell or cells and copy/cut them to the clipboard, a pale blue frame is left around those cells; the frame is currently only visible if the gridlines are toggled off (they're working on getting something more visible, similar to the dotted lines in Excel). You can then either place your cursor in another cell and hit Return, in which case the copied/cut cells get pasted there, or you can hit Esc to dismiss this frame.
So I'm wondering - is there some way of getting any documentation of these and similar functionalities into the NeoOffice Help? I've asked them how this works in their OOo builds, but I guess this also goes for any other stuff, like the Media Browser and so on, too.
I'm just concerned that new users are going to find stuff in NeoOffice that's not in any way covered in the Help. Sure, they can just come here and we can tell 'em but if there were a way to add this to Help, much the better. Alternatively, maybe there could be an extra text doc in the d/l which documents the 3rd-party features in some way. I'm not sure how important others will feel this is - its seems worth thinking about.
Unfortunately, changing the help documentation requires changing the OpenOffice.org build. There is just no way around it. The help files for all of OpenOffice.org are in one place and they consist of a big list of XML files and matching localization files that all must be run through OOo's custom "help compiler" every time their is a change.
Running this help compiler for all of the files and localizations usually takes a full day on my G5 PowerPC machine. Even if you could provide workable patches to the OpenOffice.org help files, the respin time and the need to put out a new release and a whole new set of language packs makes editing these files in our builds pretty much unworkable.
If you are really interested in getting new help text added, you may want to write the help yourself and submit the changes to Novell's ooo-build engineeers. The ooo-build code already contains modifications to the OOo help source files so adding your content, if it is fairly simple text, may be something that they can handle.
One other alternative is that we can exclude the ooo-buiild patches that add this functionality from NeoOffice 3.0 Early Access. That may be overkill, but it is an alternative that I can implement before our 15 January 2009 release.
Oh, no - way too good to delay! In the short term, folk can always ask on the forum . I think the most low-maintenance route would be to put together a doc that documents all the 3rd-party additions in some fairly basic way - what/where they are, what they do, how to use them - get it translated into a few languages and add it to the distro, maybe as an odt. It shouldn't be too in-depth - so it shouldn't take up more than 100 Kb extra at most, and would only need editing when 3rd-party functionality gets added or updated.
This is something I'd be happy to take on after the new year. I'll gather the info and draft an English version, and then run it by you. If you're into me doing this, just let me know which oo-build (and other 3rd-party) code items have been added, and I can take it from there.
- padmavyuha
BTW, the oo-build folk say they don't want to touch the Help code... and who can blame them?
Oh, no - way too good to delay! In the short term, folk can always ask on the forum . I think the most low-maintenance route would be to put together a doc that documents all the 3rd-party additions in some fairly basic way - what/where they are, what they do, how to use them - get it translated into a few languages and add it to the distro, maybe as an odt. It shouldn't be too in-depth - so it shouldn't take up more than 100 Kb extra at most, and would only need editing when 3rd-party functionality gets added or updated.
I would recommend a NeoWiki article as it is 1) indexed by Google, 2) doesn't require a patch to edit, and 3) is more likely to have up-to-date translations. Burying it in the .dmg file really is an out of the way place to put support information and having it in the NeoWiki allows narf, I, and other support volunteers to quickly provide links to the latest information if users ask.
On a side note, I found where ooo-build's icon files are for the Toggle Grid Lines toolbar button so I can include those in my next Neo 3.0 EA test build.
Ideally, the NeoOffice help content would contain info on all of the added functions, and they will also be in the NeoOffice User Guide. As a bare minimum, perhaps it would be possible to make stubs for these features in the help files that point towards the NeoWiki?
In this way, curious users are pointed at least somewhere...
-Oz _________________ "What do you think of Western Civilization?"
"I think it would be a good idea!"
- Mohandas Karamchand Gandhi
Ideally, the NeoOffice help content would contain info on all of the added functions, and they will also be in the NeoOffice User Guide. As a bare minimum, perhaps it would be possible to make stubs for these features in the help files that point towards the NeoWiki?
I don't think I was clear about editing the OOo help: it is a major effort. Putting only a little content does not reduce the effort required and making the smallest change shuts down all development and bug fixing for a minimum of a day. Fundamentally, it breaks the one thing - rebuilding the OOo code only a few times a year - that allows us to provide the level of support that we do.
I don't have several empty days to spare to implement this. Touching any of the OOo help files is a significant expansion of our scope and, frankly, IMO it requires far too many of our limited resources for one toolbar button particularly since the past tells me that we will be inundated with lots of critical bugs once NeoOffice 3.0 Early Access is released.
I hadn't thought of a wiki entry - that makes the most sense, as it can be pointed to from so many places - and would be a good showcase for some of what makes NeoOffice unique too. And as you say, it's instantly updatable, so any changes that get made to the app can be reflected instantly in the wiki.
The wiki would just have to make it clear that it's referring to the latest version/patch of NeoOffice when it talks about 3rd-party additions, as I guess v2.2.5 and v3.x.x will diverge more and more as time goes on, but some people will still be using 2.2.5 for quite a while, depending on their OS version.
Anyway, I'll get back on this after the 'festive season' is over.
As for pointing to it from the app itself, I don't suppose it's an option to put a wiki link in the About NeoOffice box, is it? That would be very low maintenance compared to any messing around with Help. Lots of apps have a support link in their About box, and directing folk to the wiki in the first instance could be a Good Thing - might take some pressure off the support forum and developers come v3 .
I just had an interesting reply from Kohei at ooo-build:
Quote:
So far we don't have any documentation for ooo-build specific features, since it never occurred to us that we needed to write it (until probably when Rene asked about it a few weeks ago). If there was, I'm sure it would be available within ooo-build under LGPL license, the same license the rest of our code is released under.
Joined: Feb 12, 2005 Posts: 607 Location: Australia
Posted: Wed Dec 17, 2008 5:33 am Post subject: user guide volume 2
Hi padmavyuha
If you want to give me the text of what would be going in NeoWiki, it is still possible to add it to volume 2 of the user guide. As you know, I have added in some material about NeoOffice 3.0 already [PDF file importing is a good example of that]. But I need it by the weekend really, If I am going to get the thing finished by Xmas day.
he wiki would just have to make it clear that it's referring to the latest version/patch of NeoOffice when it talks about 3rd-party additions, as I guess v2.2.5 and v3.x.x will diverge more and more as time goes on, but some people will still be using 2.2.5 for quite a while, depending on their OS version.
If they start to diverge too much, we can always split the page in two.
Maybe we should decide on a wiki URL now and then Peter can include the URL in the manual with the caveat that the page is still being developed or something?
Smokey _________________ "[...] whether the duck drinks hot chocolate or coffee is irrelevant." -- ovvldc and sardisson in the NeoWiki
Joined: Apr 25, 2006 Posts: 2315 Location: Montpellier, France
Posted: Wed Dec 17, 2008 11:42 am Post subject: Re: user guide volume 2
aussie149 wrote:
Hi padmavyuha
If you want to give me the text of what would be going in NeoWiki, it is still possible to add it to volume 2 of the user guide. As you know, I have added in some material about NeoOffice 3.0 already [PDF file importing is a good example of that]. But I need it by the weekend really, If I am going to get the thing finished by Xmas day.
Cheers
Peter
Why would it have to be finished by Christmas? It makes little sense to me, as the next major NeoOffice release (3.0 Early Access) won't be released until January 15th, and the final version much later.
In my opinion, it would make more sense to relase it (especially if it contains info about version 3.0) either when Early Access is released, or when the final version is released…
You cannot post new topics in this forum You cannot reply to topics in this forum You cannot edit your posts in this forum You cannot delete your posts in this forum You cannot vote in polls in this forum You cannot attach files in this forum You cannot download files in this forum
).
