Re: [emacs-wiki-discuss] Re: Documentation

[pll+ew]

In a message dated: Thu, 18 Mar 2004 23:04:16 +0800
Sacha Chua said:

>(Another thing that still needs work: documentation. I'm fine with
>complexity, but people here are starting to find planner scary...)

I think I'm the one that started this sentiment, sorry about that.

Documentation is sorely needed if only to help some people get
started. emacs-wiki mode is wonderful for just writing wiki-like pages
(though, auto-wikification of newly loaded pages via M-x
emacs-wiki-find-file would be really nice).

Planner mode I haven't delved into overly much yet, mostly because
"I just don't get it".  Most of what I don't get is planner's 
relation to emacs-wiki.  Perhaps it's my use model.  I look at the 
planners and wikis as fundamentally unrelated items.

Planners are for keeping track of 'ToDo' items.  For example, on my 
Palm Pilot, there's a ToDo list which simply is a list of items with 
priorities and due-dates (it might also be relevant to note that I 
have never used this feature of my Palm Pilot in the 8 years I've had 
one.  My wife is a wonderful "list maker", I despise them :)

Wikis are for documentation.

I can perhaps see why one might want to link to the docs in a wiki 
from a task item in a planner, but by an large, I see the two as 
completely separate.  I see planners as something personal that no 
one but me ever sees, where as documentation/wikis are specifically 
for publishing your thoughts so others can read them.

What I might use planner for is something along the lines of project
management (another thing I despise, mostly due to it's similarity to
micro-management ;)  If I can have tasks which can be prioritized with
due-dates, but also show dependany upon/parallelism with other tasks
in an easy to use notation style, then I might have more of a use for
planner beyond my own personal "ToDo lists" (and I could export to 
create some  fancy-schmancy gantt chart thingy for the management 
weenies... ;)

I think I've also seen mentions of M-x remember, Muse, and BBDB here. 
I'd be interested in how these relate to emacs-wiki and/or planner 
also.

(Hmm, I just found the planner tutorial at the emacswiki site.  
Perhaps I'll spend a few moments there today :)

One thing which I personally would find helpful, at least on the wiki,
would be if people could explain what they're lisp code contributions
actually do and where to put them.  For example, from the emacswiki
site:

Michael Allan Dorkman manages a number of wikis underneath a main directory
with this Lisp snippet:

 (defun subwiki (project)
    (list project
      (list 'emacs-wiki-directories (concat "~/Wiki/" project))
      (cons 'emacs-wiki-home-page "WikiIndex.html")
      (cons 'emacs-wiki-publishing-directory (concat "~/public_html/" project))
      (cons 'emacs-wiki-project-server-prefix (concat 
"http://localhost/~mdorman/";
       project "/"))))

 (setq emacs-wiki-projects (list (subwiki "Foo")
                                 (subwiki "Bar")
                                 (subwiki "Wombat")
                                 (subwiki "Lemur")))
 (planner-update-wiki-project)


Not really knowing e-lisp, I find this a little intimidating, but 
more importantly, confusing.  I think it's great that Michael is able 
to use this lisp snippet, but where and how?  What exactly does this 
code do for him that allows him to manager a number of wikis 
underneath a main directory?  Where does this code snippet go? In is 
.emacs file?  In some other file in his config directory? In the 
emacs-wiki.el file?

I think there is an  assumption made by many emacs users that everyone
knows lisp, and knows how things are supposed to work wrt emacs.  As a
result, I often find lisp snippets like the above on the web with
comments like:  

 Here, use this lisp code to do X.

Unfortunately, I seldom know where I'm supposed to put them. I tend
not to want to blindly throw things in my .emacs file, partially out
of fear that it will break something I don't know how to fix, but also
because I think that my .emacs file is already too big and unwiedly.
Pehaps this is just me, and I my need to understand everything *and*
keep it neat at the same time :)

Thanks!
(now off to lear planner mode :)

-- 
Seeya,
Paul

GPG Key fingerprint = 1660 FECC 5D21 D286 F853  E808 BB07 9239 53F1 28EE

         If you're not having fun, you're not doing it right!