feature request: more extensive guide for using the diary/journal feature

[alexandreroberts]

I'm not sure you're taking "feature requests," but if you are, I wanted to ask if you'd be willing to add a bit more to the documentation about how to set up a diary/journal on Wiki.vim. I like the minimalist approach you've taken here in contrast to Vimwiki, but I am having a bit trouble with the basics of setting up a diary. In particular, I don't know how I am supposed to use :WikiJournalIndex; it seems to output the index, but what I want is to create/jump to a separate file containing (and updating) the index that this command outputs (by analogy with :WikiIndex). In other words, I need help with the basics, not the finer tuning that the documentation details. Maybe you could just briefly describe the basic first steps to setting up a diary/journal like you do for the personal wiki? Thank you for your consideration.

[lervag]

I'm not sure you're taking "feature requests,"

I am :)

I wanted to ask if you'd be willing to add a bit more to the documentation about how to set up a diary/journal on Wiki.vim.

Yes, I could do that. But let's have the discussion here first; you can help me figure out what would be helpful content. If that's fine by you?

In particular, I don't know how I am supposed to use :WikiJournalIndex

Good question. I never use that myself. I've kept it mostly because I know some people want and use it.

it seems to output the index

Yes, that's right.

but what I want is to create/jump to a separate file containing (and updating) the index that this command outputs (by analogy with :WikiIndex).

That's a valid feature request. But let's continue the discussion somewhat first before I properly consider if I should add this (or change the current WikiJournalIndex).

In other words, I need help with the basics, not the finer tuning that the documentation details. Maybe you could just briefly describe the basic first steps to setting up a diary/journal like you do for the personal wiki? Thank you for your consideration.

Yes, sure. I'm out of time now, but I'll give a brief explanation of how I use the journal features.

[alexandreroberts]

Thank you! When you get the chance, a brief explanation of how you use the journal features would be a great help. I've never used any of the vim/wiki tools for a journal, so I don't have a good sense of what exact features to expect or how a standard workflow works, but I can tell you what kind of use case I am imagining.

I mostly see it as a way to keep track of two types of things:

1. a log of when I do mundane daily tasks like calling a repairman or when a repairman comes and does work so that I have some sort of record I can go back
2. notes on work-related events, meetings, etc.

Currently I make notes of such things, if at all, in a haphazard array of note files scattered around various directories. This works well enough, but it is a bit of a pain to have to navigate to the right directory before I begin, and the organization isn't great (I tend to forget where I've put such notes and then end up having to rg my way back to them anyway).

So I thought that with a wiki.vim journal I might be able to open nvim and execute a command to jump to a new journal file (which I do know how to do with wiki.vim) and another command to jump to an index file containing the up-to-date output of the current :WikiJournalIndex command.

So maybe that is just a single feature request related to :WikiJournalIndex. But a description of what you do would certainly be helpful and would probably point out uses/features that I am missing.

[lervag]

Thank you! When you get the chance, a brief explanation of how you use the journal features would be a great help.

First, I think it is important to note that there is no single way to do this. My way works for me; perhaps it may work for you. Perhaps not.

So, my workflow looks like this:

My wiki journal is more or less purely work related. I keep a separate personal diary with a brief memoir for each day, but that is not based on wiki.vim.

I keep a daily work journal where I use :WikiJournal to open todays entry. In each entry, I tend to write a short memo on what I did that day. This is mostly formatted as various lists. One such list may look like this:

Project/Activity header
* Jira-link1: title
  * comment
* Jira-link2: title
  * comment
  * comment
* Jira-link3: title
  * comment

I tend to plan my work week each Monday by manually writing and maintaining TODOs for each day in the week. I also have an entry for the next Monday where I put TODOs that are not for the present week.

This way, my journal is literally a task tracker where I write quick comments about tasks when I work on them. I more or less never add "real" content in a journal entry. Instead, I create links to my main wiki and put valuable content there. If I work on something related, then the related content is updated and available regardless of which day I'm journalling.

If I'm curious what I did at a particular date, I use calendar.vim to find the date and open the corresponding entry. See my related config here:

• https://github.com/lervag/dotnvim/blob/e95d410f5148b452a0458bb2e1fc8d3110c7799e/lua/lervag/init/packages.lua#L1330-L1342
• https://github.com/lervag/dotnvim/blob/main/ftplugin/calendar.lua

I'm generally never interested in any form of journal index. The calendar.vim interface is more or less everything I need in that regard.

I also write weekly and monthly summaries. I use the WikiJournalTo* commands to make these summaries. I write them in retrospective. I use my other plugin lists.vim which has a command ListsUniq that I use to quickly write and combine these summaries.

Over time, the journal entries have a great value in that it is easy to go back and see what I did at a particular point in time. The summaries make it easy to get a larger overview. I don't use them often, but when I do, I'm glad I have them. I also find the process of writing all of these things useful as it makes me think about what I'm doing - both the planning part and the retrospective part.

---

I mostly see it as a way to keep track of two types of things:

1. a log of when I do mundane daily tasks like calling a repairman or when a repairman comes and does work so that I have some sort of record I can go back

I keep such logs in my wiki for the related stuff. E.g., I have a wiki page for my house where I keep a log of repairs and similar. I keep a log of other things in a similar manner.

2. notes on work-related events, meetings, etc.

Yes, that's how I use my journal.

So I thought that with a wiki.vim journal I might be able to open nvim and execute a command to jump to a new journal file (which I do know how to do with wiki.vim)

:WikiJournal

and another command to jump to an index file containing the up-to-date output of the current :WikiJournalIndex command.

This is currently not directly possible. But I'm not sure if it is really necessary?

[alexandreroberts]

That is a great help, thank you! I see what you mean, that a standing journal index file may not really be necessary. It sounds like what I actually should be learning to do is to use the normal wiki pages as a way to organize repair logs and such.

I think what I haven't yet figured out with the wiki is how to (or whether I need to) organize the pages. As I try it out I have been making the WikiIndex page my starting point and then trying to find a good place to fit in whatever new note I am creating, but maybe it would be better to just draft free-standing wiki pages for each topic and then later find out how best to link to them from the index page? In any case, I think your documentation already does describe how you deal with that, so I will look at it more closely.

[lervag]

That is a great help, thank you!

I'm glad you find it useful! If you think some of my comments may be useful as content in the docs (e.g. similar to the subjective guide in :help wiki-intro-guide), please let me know. Also, feel free to give some comments to which parts/which insights may be most relevant to communicate.

I see what you mean, that a standing journal index file may not really be necessary. It sounds like what I actually should be learning to do is to use the normal wiki pages as a way to organize repair logs and such.

Yes, that is personal experience and as such, my current opinion on the matter.

I think what I haven't yet figured out with the wiki is how to (or whether I need to) organize the pages. As I try it out I have been making the WikiIndex page my starting point and then trying to find a good place to fit in whatever new note I am creating, but maybe it would be better to just draft free-standing wiki pages for each topic and then later find out how best to link to them from the index page? In any case, I think your documentation already does describe how you deal with that, so I will look at it more closely.

Yes, I believe my :help wiki-intro-guide does have some of my thoughts on this matter. You really should take note of my comments about having your notes readily available! E.g. a global keyboard shortcut like <alt>+n to open your WikiIndex and perhaps another <leader><leader> or <leader>ow to open a page search. When you feel like going from a thought to Vim/neovim open with the relevant wiki page is effortless (takes less than a second), then it will feel much easier to actually use the wiki to take notes.

A couple of additional comments:

• I STRONGLY believe the value of a personal wiki grows with time as long as you keep using it!
• I use my WikiIndex more as a simple note book where I put things I want to follow up on. I don't use it as a way to link things in general. Thus, most (99.99%) of my wiki content does not have a link from index.wiki.
• I try to spend some time every week to go through content I've added to my index and act on it. It usually means reading something I've come across that I find of interest and perhaps taking some notes in relevant places.
• You should try to find a good balance of spending some time on 1) structuring your content, and 2) not worrying about structure at all! I think structure is very useful and valuable, but it is often difficult to understand an optimal structure for some content in the beginning. Thus, keep working on your relevant personal notes in an unstructured manner. When you realize that something would benefit from some structure and you feel you know how you can do that, then put the hours in to do just that.

[alexandreroberts]

I think you could really incorporate everything you wrote to me above into the documentation for a "suggested wiki.vim journal workflow". If I had to choose the parts most useful to me, I would edit it down to this:

First, I think it is important to note that there is no single way to do this. My way works for me; perhaps it may work for you. Perhaps not.

My workflow looks like this:

My wiki journal is more or less purely work related. I keep a separate personal diary with a brief memoir for each day, but that is not based on wiki.vim.

I keep a daily work journal where I use :WikiJournal to open today's entry. In each entry, I tend to write a short memo on what I did that day. This is mostly formatted as various lists.

I tend to plan my work week each Monday by manually writing and maintaining TODOs for each day in the week. I also have an entry for the next Monday where I put TODOs that are not for the present week.

This way, my journal serves as a task tracker where I write quick comments about tasks when I work on them. I more or less never add "real" content in a journal entry. Instead, I create links to my main wiki and put valuable content there. If I work on something related, then the related content is updated and available regardless of which day I'm journalling.

If I'm curious what I did at a particular date, I use calendar.vim to find the date and open the corresponding entry. See my related config here:

* https://github.com/lervag/dotnvim/blob/e95d410f5148b452a0458bb2e1fc8d3110c7799e/lua/lervag/init/packages.lua#L1330-L1342

* https://github.com/lervag/dotnvim/blob/main/ftplugin/calendar.lua

I'm generally never interested in any form of journal index. The calendar.vim interface is more or less everything I need in that regard.

I also write weekly and monthly summaries. I use the WikiJournalTo* commands to make these summaries. I write them in retrospective. I use my other plugin lists.vim which has a command ListsUniq that I use to quickly write and combine these summaries.

Over time, the journal entries have a great value in that it is easy to go back and see what I did at a particular point in time. The summaries make it easy to get a larger overview. I don't use them often, but when I do, I'm glad I have them. I also find the process of writing all of these things useful as it makes me think about what I'm doing - both the planning part and the retrospective part.

I reserve my journal for work-related events, meetings, and other notes.

As for mundane tasks and notes, I keep a log of such things in my wiki for the related stuff. E.g., I have a wiki page for my house where I keep a log of repairs and similar. I keep a log of other things in a similar manner.

I also think some of your bullet-points about how you use the main wiki ("A couple of additional comments") would be helpful to add as well, especially where you say that you don't use the wiki index to link to all the other pages. From the documentation as it now stands I had actually gotten the opposite impression somehow, I think because you say that you use the index page as a scratchpad but then find proper homes for each note later, and I just assumed that what this meant was replacing the note in the index with a link to where the note now lives. Now that I understand what you do, it makes much more sense and seems much more manageable.

As for shortcuts, I made a few zsh scripts/aliases to open a new Wiki page (ww), the Wiki index (wi), and today's journal entry (wj).

In my vimrc, as universal mappings, I have added:

nnoremap <leader>wi :WikiIndex<CR>
nnoremap <leader>wj :WikiJournal<CR>
nnoremap <leader>ww :WikiOpen<CR>

I also added further mappings to my after/ftplugin/wiki.vim (the first two on analogy with Tim Pope's unimpaired plugin):

nnoremap [j :WikiJournalPrev<CR>
nnoremap ]j :WikiJournalNext<CR>
nnoremap wji :WikiJournalIndex<CR>
nnoremap wfp :WikiFzfPages<CR>
nnoremap wft :WikiFzfTags<CR>

[lervag]

Thanks for the useful feedback! I'll make an update where I try to incorporate this into my docs. I hope you don't mind if I do this via a PR and ask you (and anyone else who may be watching) for a review before I merge it.

By the way: there are already some global shortcuts available - you are aware of them, right? You can also adjust these defaults by changing the g:wiki_mappings_global dictionary. The docs should explain how to do this with an example.

https://github.com/lervag/wiki.vim/blob/96bb3c921d369df3e089ff6af677b53fe8146166/plugin/wiki.vim#L107-L110

Similarly, there are quite a few buffer local defaults, here:

https://github.com/lervag/wiki.vim/blob/96bb3c921d369df3e089ff6af677b53fe8146166/autoload/wiki/buffer.vim#L145-L148

These can also be changed/adjusted via g:wiki_mappings_local.

As for shortcuts, I made a few zsh scripts/aliases to open a new Wiki page (ww), the Wiki index (wi), and today's journal entry (wj).

I've found it VERY useful to have a desktop shortcut that open neovim in a new terminal window with the wiki index. That allows me to go from thought to wiki very fast even when I'm not already in a terminal. E.g. when I'm browsing, reading PDFs, etc.

[lervag]

I've updated the guide in the docs with a section on the journalling based on this discussion. I would be very grateful if you cared to read it and give some feedback. The guide starts here:

https://github.com/lervag/wiki.vim/blob/c3143806da2655f58ad0b919468adffa54d5d8dd/doc/wiki.txt#L168

And the journal section starts at line 278.

[alexandreroberts]

I have read the portion you linked, and I think the updated version is great. The changes you made to the part about the personal wiki are very helpful, as is your account of how you use the journal feature. Thank you for taking the time to explain all this (and, of course, for making this plugin in the first place!).

[lervag]

I'm glad you find it useful! :)