(Moved it here because it was unappropriate for the front page, but didn't know where else to put it.)
Discussion about this documentation#
Structure by user group#
It might be a good idea to sort the documentation accordings to the
information needs of different user groups.
See Proposal for Naming of Documentation Pages.
Some ideas how to structure a documentation page:
Proposal for Content of Documentation Pages.
Overview of proposed name mapping: Wiki.DocumentationMap
Structure by (technical) level#
The document structure seems easier if the basic progression User->Administrator->Programmer (or less complex to more complex) is kept intact (as it is somewhat on the main JSPWiki page). (I switched 'Features' and 'Installation and Configuration' because of this reason.) -- Blaine Willhoft
Blaine: I agree with your comment about progression from easy to hard and user to programmer. However, there may be a few plugin things that users want to know. I'm not sure. If so, perhaps we can introduce those things under particular tasks. Do users use plugins?
I don't really know any evidence either way as to whether users use plugins or not. If it's intended, though, that basic users be able to use them, it probably should be mentioned in the 'user' section. Perhaps a basic overview of the features of JSPWiki - including plugins - from a purely 'user' point of view would be good to have in the first section. -- Blaine Willhoft
--JDuprez My regular users use mostly the simplest plugins (TableOfContentsPlugin, InsertPagePlugin, ReferringPagePlugin). I added examples of them to my Edit Page Help. All other plugins are used only by experienced users, if at all. RecentChangesPlugin, e.g., is only ever used by the administrator (me:o), hardly adjusting the default periods found in the default pages [RecentChanges], and [RecentChanges].
Structure: customization points#
One of the things I've missed even in former version's docs is a repository of ways to customize JspWiki aspects, contents, access policy,... Basically, there's:
- the default (default template, default loose access policy, default content)
- the customs (custom template, custom security policy and ACL, custom plugins,...)
For example, if one wants to customize the display, he can use the default teplates, and only edit the jspwiki.css. If he wants further custom look-and-feel, he can elect or develop custom templates.
Access policy is also likely to be more restrictive than the default, even on an intranet. Suggestions to do that would be welcome. Typical policies I can think of are:
- Free-for-all (default policy)
- Free-for-all reads, authenticated edits (simple policy edit)
- Authenticated access only (simple policy edit)
- Group-specific access rights (will require per-page ACL, or naming conventions).
- Locked users list (policy edit, plus JSP hacking)
- Admin-locked user list (this one I haven't figured out yet)