Sad loss of useability in SDK

[TerryE]

This post doesn't fit well in the Installation of API forums, but the 2.4 SDK has introduced a very regrettable backwards step in usability. Prior to 2.4 the SDK included a copy of the Developers Guide. This had some major advantages:

• It was locally installed
• It was broken down into chapter size pages.

This meant that it was very usable: it was fast; you could rapidly page down through it and search (browser based) was quick and easy.

The new wiki based DG is basically a migration of the existing SDK and at the moment add little content over the 2.3 XML DG. Of course I believe that we should make the DG content available on the Wiki, but this should be as a supplement not a mandatory replacement for the offline DG. It is pretty unusable for the power user because:

• You have to be online to access it.
• The hierarchy is quit deep. Content that you could get to at a page level is now 4 or so levels down in the document hierachy. Moving from DG page to page can involve a number of web-page hops each taking seconds to display. This slows down my interaction by almost a factor of 10 making its use just SO annoying.

MySQL, Postgres, php, etc. all maintain equivalent online repositories, but they also include downloadable CHM and other offline formats for power users. Since this document is really for power users, this is a sad loss of user functionality. So my Qs are:

• To other power users: What are you feelings here?
  To Clayton: What was the logic behind this step?
  To anyone:: Do you have a copy of the 2.3 SDK. I deleted mine before I realised this, and http://download.openoffice.org/2.3.1/sdk.html no longer contains the 2.3.1 SDK!

[ms777]

100% agreement from my side

ms777

[Villeroy]

I'm with you. I did not read the dev-guide for quite a long time. Now your posting made me aware that I actually can't anymore. Ubuntu 7.10 should have an old SDK in it's repository.

[ccornell]

The logic was... well to open it up for community edits. The old process was very closed. There was no access to the source, and no one could help out. Putting it in the Wiki opens things up for community involvement in editing.

That said, you are definitely correct in your observations.

I'm working on things to help with filling that new hole I created. On Monday.. so two days ago, I rolled out a new Extension from PediaPress for the Wiki that allows you to generate PDFs on the fly based on "Collections". I will be creating collections of each chapter of the DG, and one overall. These collections can be turned into a PDF in a couple clicks... I have added one DG collection already, and will add more as soon as I can. The first one is the first chapter, and is linked from the first page of the first chapter:
http://wiki.services.openoffice.org/wik ... irst_Steps
The PDF link is bottom left of the article frame above the PDL statement (I have to think of a better way to present this link... maybe with a standard PDF icon as well as the text?). Click the link, then click the Load Collection link on the left under the heading "My Collection". This will take you to the Collection management page. You can click Download PDF, and in a minute or so you will have a PDF of the first chapter.

You (as in any register user on the Wiki) are free to build your own custom collections as well.

Now that the PDF export is working , we will be able to provide a PDF of the whole book, and of individual chapters.

The next step is to work with PediaPress and get the ODT export working (it will work in the same way, only instead of clicking Download PDF, you will only need to click Download ODT). I will have a really early alpha of that installed soon, and hope to take that live in the coming weeks/months (depends on a lot of things... software on server etc.).

This step will allow people to have it in ODT if they want, and also allow us to produce a nice looking book with a proper index and TOC.

The single HTML per chapter thing was a horrible maintenance nightmare, and I don't think we will be returning to that.... at least I hope not.

For online searching I added a Custom Google search to the Documentation pages:
http://wiki.services.openoffice.org/wiki/Documentation (just above the Searching and Downloading title)
This does a Google search through only the Documentation sub pages, so you can relatively quickly search the DG.

The hierarchy of the DG in the Wiki is less that optimal. It is a literal implementation of the source material, and no time was taken to rewrite any portions to make it more logical for online use. That needs to be worked on... we need to look at each Wiki page in the DG and determine is it in the right spot? were the sub sections split off logically? does it need to be merged into a higher or lower level? etc etc. all while keeping in mind that editing a long page in a Wiki is a messy affair so we want to limit the length of the pages where possible (ie we do not want a whole chapter in a single Wiki page).

This is all of course open to suggestions and improvements. The document is open source. We all have a part in it, not just me (which was the case before I ported it to the Wiki).

[TerryE]

Clayton, thanks to your response. I must admit that I never used the PDF version of the SDK. I find PDF as an online format pretty user hostile. It is really optimised for producing printed documents. For example it renders to a fixed page layout complete with headers, footers, margins etc. and the search is rather slow. I find HTML (and transformed XML) far easier to use especially through Ff 3.0 as it naturally flow to my window, and is not cluttered by page oriented furniture such as headers and footers. Search is also far more agile. The Windows CHM format being fundamentally an HTML one is equally usable.

The reality is that these documents have a low volatility, and given that I regularly download the entire source for ease of reference when I need it, the fact that I can't simply download 5Mb or so of the entire Developers Guide in some form of hierarchical HTML format is a really odd feature loss.

I also disagree strongly about can be one chapter per HTML page being horribly unusable. It might have looked horrible to the novice and the managers who want something to look sexy, and by the for as experienced developers go, it is simple, quick and it works as a reference medium. With modern browsers such as Ff 3, rendering is quite fast and both search and page up/down blindingly fast = this is really easy to use and an effective tool.

[ccornell]

PDF is just the first step... it's not the only output format I am working on ODT is next. After that... we'll have to see.

[TerryE]

Sorry Clayton, we just crossposted. I added a footnote to my last post about HTML, one chapter per page. Did you ever take a straw poll of the people who actually use the DG on a regular basis, because this was the format that I used all the time and I really liked it

[ccornell]

I also disagree strongly about can be one chapter per HTML page being horribly unusable.

I didn't say unusable.. I said maintenance was a horrible nightmare. It was a cumbersome process to build the document in the old doc methods. It was completely impossible to move the document to the WIki as the prime editing platform and still be able to generate those monster HTML pages. The Wiki cannot deal with pages as long as some of those were.. and even if it could, can you imagine what it would be like trying to edit a single Wiki page that was the equivalent of 200 A4 pages long? That absolutely had to be broken up into bite sized chunks.

That is not to say that we cannot generate HTML again... it's just that the state the document process was in prior to porting to Wiki was pretty dire to say the least. For example it was only possible to edit the source in StarOffice7, and even that required a special import filter that was limited to only SO7.

It may be possible that we can take the ODT (once that is working) and export as HTML (similar to the old process), but I cannot promise that will be done.

As it stands, as of today, we have:

• the possibility of a single PDF per chapter
• a custom Google search which is limited to the Doc subpages

The near future plan is to find a way to implement ODT generation.

Long term... I haven't thought that far out. HTML is an option, and a possibility but it is not on my plan until after I get ODT working.

[sanya]

You should be able to find it here: http://api.openoffice.org/SDK
HTH
sanya

[TerryE]

Ubuntu 7.10 should have an old SDK in it's repository.

You should be able to find it here: http://api.openoffice.org/SDK

Unfortunately not. I powered up an old Ubuntu 7.10 and installed openoffice.org-dev-doc (which is the SDK package). Nope, it refers to http://api.openoffice.org/SDK. And this page just contains dead links now. The last XHTML versions seems to be lost. Anyone want to email me a copy?

[ccornell]

On the api.openoffice.org webpage, you have a link to: http://api.openoffice.org/docs/Develope ... uide.xhtml I just checked it.. clicked around a few random pages, and it loads fine for me (Firefox 2.0.0.14)... is it not working for you?

[TerryE]

Clayton, I get the following error in Ff 3.0

Code: Select all

XML Parsing Error: 
Location: http://api.openoffice.org/docs/DevelopersGuide/DevelopersGuide.xhtml
Line Number 3, Column 527:
<html xmlns="http://www.w3.org/1999/xhtml"> ... <meta name="changed" content="2007-07-04T16:37:45"/><base href="."/>
------------------------------------------- ... --------------------------------------------------------------------^

But when you put it through the W3C validation site, its fine. Could someone else who has Ff 3.0 installed have a try?

[floris v]

Same result with the link.

[Hagar Delest]

Same error for me with FF3 (French localized) under W2k.
If I open it in Notepad2, no parsing error neither. But if I remove the <base href="."/> tag, it works with FF3 then.

[TerryE]

The <base href="."/> tag is in quite a few of the XTHML files and causes the same error. I am doing a wget -r -nc on one of Linux VMs. When it's done, I'll do a batch script to remove these tags and put a tar.bz2 of the SDK onto the forum so that those that want a local copy can download it.

[TerryE]

OK, I've get the SDK working. The text links to the local API but the API links to the Wiki. Not worth changing. The link is http://user.services.openoffice.org/en/ ... DG.tar.bz2. Enjoy.

[TerryE]

Just catching up on the API digest, I see that you've has a similar dialogue here, Clayton

http://api.openoffice.org/servlets/Brow ... om=2057914

[ccornell]

Yup. The state the Dev Guide is in now on the Wiki is definitely not the end state. It is in transition. It will remain on the Wiki as the main source, but there are several things in the works to provide the different end use formats. As I noted before, PDF was the first step.. that works now, so next... ODT.. then we can look at other delivery formats.

On the layout of the Dev Guide.. the current organization in the Wiki is not the best. It was done that way as essentially a mirror of the original material as it was before the document was opensourced. We need to look at how the doc is organized and find a nice balance between ease of editing in the Wiki and presentation. That will most likely be discussed on the API mailing list.