Doc improvement project

[ebruchez]

Currently

Our doc needs some love:

• it is in two places
  • wiki.orbeon.com (Google Sites)
  • github wiki
• it is hard to figure out
  • what is the latest and greatest
  • what is legacy
  • an overview of the doc
  • where exactly to get started
• it doesn't look good, especially on the wiki

  Priorities

  1. Starting point: It must be clear to users (current and prospective) where the doc is and how to get started.
  2. Prioritization:: We must clearly show the topics most likely to be of interest to most users. For example, they should not be confused by XForms or XPL doc if what they want to do is learned how to setup Form Builder.
  3. Quality: The doc must be consistent, easy to read and navigate, and have no broken links.
  4. Design: The doc must look reasonably good.
  5. Maintenance: The doc must be relatively easy to maintain and update.

     Implications

• Migrate the documentation from the old wiki to a single location.
• Old and obsolete doc is removed (or clearly placed in an "attic").
• Use Markdown.

  Later

• Use a site/doc generator from the Markdown.
• Version doc per Orbeon Forms release.
  • "Orbeon Forms 4.13" (say): contains only latest doc (remove SINCE markers)
  • "Older Orbeon Forms versions": contains "current" doc (including SINCE markers)
  • NOTE: This raises the question of updating older doc when fixes are made.
• Maybe: add Disqus comments do all doc pages for feedback and discussion. Is this a good idea? Do other sites do it?

  Topics to cover

  1. Overview/install (current starting point)
  2. Orbeon Forms use cases (#228) (can be on www.orbeon.com)
  3. FB/FR user manuals
  4. Form Builder and Form Runner integration (#2019)
  5. Then only XForms and other details

     Pages to migrate

• [x] Form Builder User Guide (#219)
  • [x] base doc (split if needed)
  • [x] Database Services
  • [x] Component Metadata
  • [x] decide what to do with French version of guide
• [x] Guide to Using and Writing XBL Components
• [x] Configuring a Form Runner eXist database
• [x] XBL components exposed in Form Builder
  • [x] Currency
  • [x] Data-bound Select1
  • [x] Image annotation
  • [x] Number
  • [x] TinyMCE Editor
  • [x] US State
• [x] Other XBL components in use
  • [x] Alert dialog
  • [x] Captcha components: reCAPTCHA and SimpleCaptcha
  • [x] Error Summary Component
  • [x] Source Code Editor
  • [x] XForms Inspector
• [ ] Other Form Runner pages
  • [x] Dates and times in Orbeon Forms data
  • [x] Auditing
  • [x] Importing Data to Form Runner
  • [x] Monitoring HTTP Requests
  • [x] Overriding or adding resources without changing Orbeon Forms
  • [ ] Performance, Tuning, and Sizing
  • [x] Security and XSS
  • [ ] Merge "Performance, Tuning, and Sizing" and "XForms - Performance Settings" pages #323
  • [ ] Form Runner - URIs Format
• [x] XForms
  • [x] XForms - XPath Function Library
  • [x] XForms - Logging
  • [x] Orbeon Forms XForms Tutorial
  • [x] Delayed Events
• [ ] Core platform
  • [x] Resource Managers
  • [ ] Packaging and Deployment
  • [x] Page Flow Controller
  • [ ] Page Flow Epilogue
  • [ ] XML Namespaces
  • [ ] Handling XML Comments
  • [ ] Context and Session Listeners
• [ ] Other
  • [x] Persistence API: this used a lot
  • [ ] Third-Party Java Libraries
  • [ ] Third-Party JavaScript and CSS Libraries
  • [ ] Profiling with YourKit
  • [ ] XForms - Development Environment
• [ ] XPL
  • [ ] XML Pipeline Language (XPL)
  • [ ] API - Pipeline Engine API
  • [ ] API - XPL Processor API
  • [ ] Authentication
• [ ] Maybe
  • [ ] Orbeon Forms 4 release notes
• [ ] Controls
  • [x] Dialog
  • [ ] Group
  • [x] Input
  • [x] Output
  • [ ] Secret
  • [ ] Selection
  • [x] Trigger
  • [x] Upload
• [ ] XPL
  • [ ] XPL - Command Line Applications
  • [x] XPL - Non-XML Documents
• [ ] XForms
  • [x] XForms - Advanced Submissions
  • [x] XForms - Asynchronous Submissions
  • [ ] XForms - Attribute Value Templates
  • [x] XForms - Actions
  • [x] script and action actions for scripting
  • [x] XForms - Events
  • [ ] XForms - Extensions
  • [x] XForms - Focus
  • [x] XForms - JavaScript and CSS Resources
  • [x] XForms - Noscript (Accessible) Mode Guide
  • [ ] XForms - Other Extensions
  • [ ] XForms - Performance Settings
  • [x] XForms - Refresh Events
  • [x] XForms - Using the Orbeon Forms XForms Engine with Java Applications
  • [x] XForms - Variables
  • [x] XForms - XForms Inspector
  • [x] XForms - XPath 2.0 Support
  • [x] XForms - XPath Analysis
• [ ] Development
  • [ ] [DUP?] XForms - Development Environment
  • [ ] Code Conventions
  • [ ] JavaScript Development
  • [ ] Orbeon Source Code Repository
• [ ] Misc
  • [ ] Orbeon Form Runner - Programmer and Administrator Guide
  • [ ] Error Page
• [ ] Processors
  • [ ] Processors - Cache Processor
  • [ ] Processors - Converters
  • [ ] Processors - Directory Scanner
  • [ ] Processors - Email
  • [ ] Processors - File Processor
  • [ ] Processors - HTTP Serializer
  • [ ] Processors - Java
  • [ ] Processors - LDAP
  • [ ] Processors - Other
  • [ ] Processors - Other Generators
  • [ ] Processors - Other Serializers
  • [ ] Processors - Pipeline
  • [ ] Processors - Request Generator
  • [ ] Processors - Scheduler
  • [ ] Processors - SQL
  • [ ] Processors - URL Generator
  • [ ] Processors - Validation
  • [ ] Processors - XForms Submission
  • [ ] Processors - XInclude
  • [ ] Processors - XSLT and JAXP (TrAX)
  • [ ] Processors - Zip and Unzip

    Examples of docs to look at

• http://slick.typesafe.com/doc/2.0.0/
• sbt: you can switch the version at the top

[avernet]

A first step would be to create "table of content" pages for Form Runner and XForms, and link to those pages from the wiki home page.

[ebruchez]

Maybe related: I started a list of Orbeon Forms Features.

[acspike]

A users' perspective: I really appreciate the approach taken by PostgreSQL and Django where there is new documentation for each version and multiple versions are visible at once. Much less confusing than seeing each page of docs split for 3.9 and 4.0+ versions.

[ebruchez]

Agreed. The 3.9 doc is probably of very little use right now, but for the various 4.x releases it would be nice to have doc in sync. But to get there we must first finish migrating doc from the old Google Sites wiki to Markdown.

[ebruchez]

This is still current. We have since migrated some pages on a need basis, but there is a lot of remaining work to do.

[ebruchez]

Possibly gitbook could be used.

[ebruchez]

Update: We have made progress migrating quite a bit of doc recently. Most of the Form Builder / Form Runner documentation we had on the old wiki in particular is now migrated.

[ebruchez]

Update: All files converted to Markdown! Now need to move remaining ones to GitBook.

[ebruchez]

Also noting this funny page Programming with XForms. It covers a few XForms topics, but not the view for example. We should probably just remove it.

UPDATE: Done.