Hey Martin, Thanks for sending this, thoughts below:
-----Original Message----- From: Martin Desruisseaux <[email protected]> Organization: Geomatys Reply-To: "[email protected]" <[email protected]> Date: Tuesday, July 9, 2013 9:55 AM To: Apache SIS <[email protected]> Subject: Web site, Maven site and javadoc >Hello all > >We have 2 kinds of "high-level" documentation (excluding the developer >guide and the wiki for now): > > * The web site (source files: *.mdtext) > * The maven site (source files: *.apt) > >I guess that we need some consolidation. Is the following understanding >right? Yep sure as long as it makes sense. > > * Many (most?) Apache projects do not use Maven web site as their main > portal. Yep a lot of them don't. Some do, it just depends. Apache OODT for example uses a combination of Maven generated pages, transformed with XSLT and an external Python tool [1] to combine the Maven pages with XHTML that we keep statically. Hadoop uses a combination of Maven generated site and static pages. Tika uses APT files directly in Maven. Lucene and Solr both store their web pages in Confluence and transform the background using CSS and stylesheets. > * If the above is right, then Maven web site is accessible only on the > Jenkins server [1]. Yep. But it doesn't have to be. We can combine different hooks and other facilities in concert with the Apache CMS per [2]. We just need to put in the hooks to make it call Maven and build the website. Right now it simply builds the website based on the standard HTML or default policy for Markdown. > * According Apache policy, content of Jenkins server is for developers > only. Yes and no -- it's not meant to be "official" at all - just our test server. The "official" SIS page is at http://sis.apache.org/ > * Consequently, all current *.apt pages giving instruction to users > shall move to *.mdtext files on the web site. I think that would be a better place for them, unless we can combine the Maven build somehow with our CMS. We don't *have* to use the CMS to build our site. OODT doesn't use the CMS. At a minimum we *do* need to use SVNpubsub (which the CMS uses underneath) to make sure site changes are propagated. > * Conversely, the release-management page [2] currently on the web > site could move to the Maven site. It could. It depends on what the maintainers of those pages are comfortable with and who has more time and energy and what tools/preferences they have. > * Javadoc, currently on the Maven site, needs to be copied manually. > But where? The overall point you're trying to make is that there are several places of SIS documentation yet we don't have a "unified" web site for it. Suresh and Ross Laidlaw and Estrada and Hart tried to address the need that we "need a SIS website" but no one took a step back and tried to design the website in concert with the docs you are producing in Maven and Jenkins. So, someone should do that. We should probably start from the "drawing board" per se, and just sit down and storyboard what the SIS website look and feel should be, and where things should go, then work to come up with processes by which the information in those pages is populated. > > >The advantage of Maven *.apt files is that a search-and-replace in the >source code includes those APT pages, which is very convenient for >maintaining instructions that need to stay synchronized with the source >code, while instructions that are considered stable can more easily be >on the web site. I agree with this in general. >Consequently, should I move the current >"release-management.mdtext" file to a Maven APT file, before edition for >the SIS specificities noticed in previous emails? I think we can take an incremental approach to this -- if you'd like to maintain release management as a Maven APT file that's find, but I don't think it should be "moved" -- more so -- copied might make more sense. Since Suresh I believe added the file originally and I know he is more familiar with the CMS than Maven APT (or at least I think) a copy would solve both problems and let the person most willing and with the most time to keep the page up to date, and then perhaps after a while we deprecate the other page depending on what we see. Sound correct? Cheers, Chris ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Chris Mattmann, Ph.D. Senior Computer Scientist NASA Jet Propulsion Laboratory Pasadena, CA 91109 USA Office: 171-266B, Mailstop: 171-246 Email: [email protected] WWW: http://sunset.usc.edu/~mattmann/ ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Adjunct Assistant Professor, Computer Science Department University of Southern California, Los Angeles, CA 90089 USA ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
