doc/todo/basewiki_should_be_self_documenting.mdwn

   1 The pages in the basewiki should be fully self-documenting as far as what
   2 users need to know to edit pages in the wiki. [[HelpOnFormatting]]
   3 documents the basics, but doesn't include every preprocessor directive.
   4
   5 Note that there's a disctinction between being self-documenting for users,
   6 and being complete documentation for ikiwiki. The basewiki is _not_
   7 intended to be the latter, so it lacks the usage page, all the plugin
   8 pages, etc.
   9
  10 I've made some progress toward making the basewiki self-documenting by moving
  11 the docs about using templates, shortcuts, and blogs from the plugin pages,
  12 onto the pages in the basewiki.
  13
  14 Here are some of the things that are not documented in full in the
  15 basewiki:
  16
  17         joey@kodama:~/src/ikiwiki/doc/plugins>grep usage *
  18         aggregate.mdwn:## usage
  19         graphviz.mdwn:page.  Example usage:
  20         graphviz.mdwn:amounts of processing time and disk usage.
  21         img.mdwn:## usage
  22         linkmap.mdwn:set of pages in the wiki. Example usage:
  23         map.mdwn:This plugin generates a hierarchical page map for the wiki. Example usage:
  24         postsparkline.mdwn:# usage
  25         sparkline.mdwn:# usage
  26         sparkline.mdwn:more detail in [its wiki](http://sparkline.wikispaces.com/usage).
  27         table.mdwn:## usage
  28
  29 Meta is another one.
  30
  31 The holdup on documenting these in full in the basewiki is that I'm not sure
  32 where to put the docs. [[HelpOnFormatting]] should stay as simple as possible
  33 and just give examples, not full lists of availavle parameters, etc. And
  34 it's bad enough that [[blog]] uses that toplevel namespace, without adding
  35 lots more toplevel pages to the basewiki. ([[blog]] really needs to be moved..
  36 I have several wikis that override it with their actual blog content).
  37
  38 Maybe the thing to do would be to make a meta/ or usage/ or wiki/ or something
  39 directory in the basewiki, and put new pages documenting how to use preprocesor
  40 directives in there.
  41
  42 Actually, if we look at the basewiki contents:
  43
  44         blog.mdwn@              pagespec.mdwn@               subpage@
  45         favicon.ico@            preprocessordirective.mdwn@  subpage.mdwn@
  46         helponformatting.mdwn@  sandbox.mdwn@                templates/
  47         index.mdwn@             shortcuts.mdwn@              templates.mdwn@
  48         local.css@              smileys@                     wikiicons@
  49         markdown.mdwn@          smileys.mdwn@                wikilink.mdwn@
  50         openid.mdwn@            style.css@
  51
  52 Most of this is meta stuff. Only index.mdwn, local.css, favicon.ico,
  53 smileys, wikiicons, shortcuts, and templates are really content/configs that
  54 are used as the base of a wiki. The rest is documentation.
  55
  56 Moving a lot of these pages could be hard though.. Lots of wikis probably
  57 link to them. Maybe the directory they're moved to could be in the search
  58 path, like the userdir is, so that simple links keep working.
  59
  60 See also: [[Conditional_Underlay_Files]]