Item2652: Enable System.InstallationGuide to be annotated

Introduce changes to InstallationGuide so that it can be annotated by creating another topic that holds the additional notes for each section being annotated. Each note is surrounded by TML markup to flag the corresponding section being annotated.

InstallationGuide is being modified to INCLUDE the annotations, rather than having another topic INCLUDE all of the sections in the InstallationGuide, as this reduces the overhead in maintaining the annotated versions of the guide.

A new helper topic, System.AnnotatedInstallationGuide, is introduced to hold the common bits of code required within the InstallationGuide and each of the annotated guides. This topic also has a search to show the annotated guides, and instructions on creating a new annotated guide.

Once these changes are deployed on foswiki.org, many of the platform-specific installation instructions listed on InstallingOnSpecificPlatforms can be converted into annotated installation guides.

---

This change will also be targeted for the 1.0.10 release.

-- IsaacLin - 17 Jan 2010

I do not understand what you are about to do.

The InstallationGuide today gets translated into ONE static HTML file which is located at the root of the installation directory. And it is a file you need to be able to open directly in your web browser without having a webserver to serve it. This means it must be fully selfcontained with no graphics, no CSS files, no JS files or anything. Just ONE html file that you can double click on in Windows and read in the browser.

The idea is that you cannot read Foswiki pages until you have installed Foswiki. And you cannot install Foswiki without some documentation how to do it.

I have at least 100 times had to remove stuff or change stuff in that guide where people linked the way we do with Foswiki topics.

I want to make sure we do not make this mistake again.

The current installation guide is a nightmare for a newbie and really needs to be simplified and not extended.

So what is it you plan to do here?

-- KennethLavrsen - 17 Jan 2010

And no matter what - I do not want Release01x00 branch to ever be in a transitional state where something is half implemented so I cannot build a release with one day notice. I often have had to do that when we had a security issue.

So please - no matter what this is all about - keep it in 1.1 scope. Ie. not for 1.0.10. (I actually hope there will never be a 1.0.10)

-- KennethLavrsen - 17 Jan 2010

Looking for feedback from any interested parties—please see http://trunk.foswiki.org/System/AnnotatedInstallationGuide and http://trunk.foswiki.org/Sandbox/InstallationGuideSolaris10 for examples of how an annotated installation guide would look like.

-- IsaacLin - 17 Jan 2010

Based on discussions, there seems to be more interest in other enhancements to the Foswiki documentation. Reverting changes and closing this item.

-- IsaacLin - 20 Jan 2010