diff options
| -rw-r--r-- | doc/todo/basewiki_should_be_self_documenting.mdwn | 60 |
1 files changed, 60 insertions, 0 deletions
diff --git a/doc/todo/basewiki_should_be_self_documenting.mdwn b/doc/todo/basewiki_should_be_self_documenting.mdwn new file mode 100644 index 000000000..d467f2f0b --- /dev/null +++ b/doc/todo/basewiki_should_be_self_documenting.mdwn @@ -0,0 +1,60 @@ +The pages in the basewiki should be fully self-documenting as far as what +users need to know to edit pages in the wiki. [[HelpOnFormatting]] +documents the basics, but doesn't include every preprocessor directive. + +Note that there's a disctinction between being self-documenting for users, +and being complete documentation for ikiwiki. The basewiki is _not_ +intended to be the latter, so it lacks the usage page, all the plugin +pages, etc. + +I've made some progress toward making the basewiki self-documenting by moving +the docs about using templates, shortcuts, and blogs from the plugin pages, +onto the pages in the basewiki. + +Here are some of the things that are not documented in full in the +basewiki: + + joey@kodama:~/src/ikiwiki/doc/plugins>grep usage * + aggregate.mdwn:## usage + graphviz.mdwn:page. Example usage: + graphviz.mdwn:amounts of processing time and disk usage. + img.mdwn:## usage + linkmap.mdwn:set of pages in the wiki. Example usage: + map.mdwn:This plugin generates a hierarchical page map for the wiki. Example usage: + postsparkline.mdwn:# usage + sparkline.mdwn:# usage + sparkline.mdwn:more detail in [its wiki](http://sparkline.wikispaces.com/usage). + table.mdwn:## usage + +Meta is another one. + +The holdup on documenting these in full in the basewiki is that I'm not sure +where to put the docs. [[HelpOnFormatting]] should stay as simple as possible +and just give examples, not full lists of availavle parameters, etc. And +it's bad enough that [[blog]] uses that toplevel namespace, without adding +lots more toplevel pages to the basewiki. ([[blog]] really needs to be moved.. +I have several wikis that override it with their actual blog content). + +Maybe the thing to do would be to make a meta/ or usage/ or wiki/ or something +directory in the basewiki, and put new pages documenting how to use preprocesor +directives in there. + +Actually, if we look at the basewiki contents: + + blog.mdwn@ pagespec.mdwn@ subpage@ + favicon.ico@ preprocessordirective.mdwn@ subpage.mdwn@ + helponformatting.mdwn@ sandbox.mdwn@ templates/ + index.mdwn@ shortcuts.mdwn@ templates.mdwn@ + local.css@ smileys@ wikiicons@ + markdown.mdwn@ smileys.mdwn@ wikilink.mdwn@ + openid.mdwn@ style.css@ + +Most of this is meta stuff. Only index.mdwn, local.css, favicon.ico, +smileys, wikiicons, shortcuts, and templates are really content/configs that +are used as the base of a wiki. The rest is documentation. + +Moving a lot of these pages could be hard though.. Lots of wikis probably +link to them. Maybe the directory they're moved to could be in the search +path, like the userdir is, so that simple links keep working. + +See also: [[Conditional_Underlay_Files]] |