forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "J.Pietschmann" <>
Subject Re: [Poll] Scope confusion?
Date Sun, 07 Jul 2002 09:44:10 GMT
Steven Noels wrote:
> * cross-project website generation with project metrics 
> (download stats) and common documentation sections
> * remote doco building for subscribed projects, Gump-like fashion
> * a documentation environment for individual projects which need a solid 
> framework for local docs generation, and distro docs packaging (think of 
> PDF here)

I'm not sure what separates the three points. Point three appear to
be the base
- Documentation framework (point 3)
   * DTDs/other schemas for describing documents
   * a set of rules, best practices and guidelines on how
     + structure the docs
     + use the XML elements
     + a directory structure
     + how to deal and embed other data: diagrams, pictures,...
   * a set of XSLT to get a common intermediary format for
   * a set of skins for different publishing formats: HTML, PDF...
   * a set of DTD/other schemas for documentation metadata
     + describe the directory structure
     + describe project wide and local (folder, directory) navigation
   * guidelines for standard documentation content, partly given
     already by specialized DTDs (should probably move to specialized
     DTDs completely)
     + project overview: management blurb, goals, dependencies
     + project organisational structure: authors, committers,
       roles, responsibilities, relations to other organisations
       (Apache, Jakarta, Apache XML...)
     + project news: actual headlines and developments (frozen
       or omitted in distributions)
     + project inner structure: branches, subprojects, components
       (hehe: heavily overloaded term, use in the broadest sense)
     + project releases or distributions (downloadables), release
       descriptions (commonly release notes and changes)
     + FAQ
     + todo list (accepted defects and feature requests, wish list)
     + plans, timetables, planned milestones, roadmaps
     + ressources outside the project (relevant standards, documents
       white papers, mailing lists...)
     + glossary
- Website publishing framework: get the publishable (ugh!) docs
   and downloadables (distributions) onto a website. Seems to be
   mixed form point 2 and point 3:
   * Metadata describing what is actually published supplied by
   * Downloadables (released distributions) provided by project.
   * Framework supplies: mechanics to trigger publishing (manually,
     by time, by dependency), extract doc source from CVS, build
     HTML, put into the server's webspace
   * Cross project link validation.
- Infrastructure
   * Standard offline content: repossitory for commonly asked questions,
     licenses, organisational details, personal data ... to be pulled
     in or referencced by individual project documentation.
   * Standard online content: Download pages, project access statistics
   * Interactive websites: feedback forms, forums, wiki, process support
- Apache project, Apache XML project etc.
   * Have certainly a FAQ ("What is Apache?"), project organisational
     structure, howtos (howto create a project, mailing list, introduce
     a new committer...)

Well, I'm not really satisfied with the description above, I hope
you get the points.
The documentation framework is the base for the other stuff:
unless you have agreed on a common structure for the documentation,
automated publishing is hardly an option. OTOH, doc writers should
not be forced to have the publishing framework installed locally
for development of the docs, it should be reasonably easy to setup
a local environment for an edit-test cycle as well as full doc
building in various formats. Ideally, the stuff needed for building
HTML should be delivered with a project's "source distribution"
without bloating it too much.

<Dream-mode> XML parsers and XSLT processors are fairly common. What
is lacking is lightweight XML pipeline processing and xinclude.
We should have (Apache) projects for this, and a lightweight JAXP
style API. Ant could have XML pipeline processing task build in.
(Well XML pipeline means: get some XML, pass it through several
processing stages, and serialize the result. No matchers, no actions,
no views, no error handling)

>           =====================================================
>                                  Ballot
>           My main interest in Forrest is:
>             [  ] building next generation
>             [  ] Gump-style remote doco building
>             [  ] industrial strength documentation framework
>           =====================================================

I'm not sure any of these really matches my personal itches.

I want to have a lightweight environment to develop docs at home: not
really sure whether this matches "industrial strength documentation
framework", though it probably should.

I want to have the posssibility to easily publish news, updated
documents and new downloadables on the FOP website. I'm not sure
whether this matches "Gump-style remote doco building", though it
probably should.

I want to have download statistics, project activity statistics,
feedback forms, integrated problem tracking, forums, wiki and
workflow support ("prepare a release", "introduce a new committer",
"create a new mailing list") online. I'm not sure whether this
matches "building next generation", though I really
hope it does. Well, this is to huge to swallow it at once, but
can hopefully be done step-by-step.


View raw message