User manual problems

[HiPhish]

Hello,

The user manual has several problems:

• pressing gO opens an empty location list
• the manual does not follow the format as outlined in help-writing
• missing topics, e.g. how to create adapters

It looks like you are generating the manual the same way Telescope does, which has the same problems.

[rcarriga]

The first two points are to do with the generation I believe, as you said. I'm not at all interested in manually maintaining documentation in a vim help file but I'd be happy to look at alternatives that can do the generation in a better way.

For the missing topics, yes you're right I just haven't gotten around to writing the docs yet. The info in the README was just written quickly to have some information out there for people to see but I'd like to have better vim docs.

[HiPhish]

Why don't you want to write the Vim help file? From what I have seen all the generators out there are broken, and even when they work the generated result is a complete eye sore. I have written a number of Vim help documents by hand and it's pretty straight-forward, I just write plain text with some very light markup. Vim help is not a fully featured markup language like for example Texinfo is.

[rcarriga]

I like to keep docs next to where they are relevant and so would have to keep the docs in emmy lua format and in vim help format, which I don't want. I'd rather have a single source of truth.

There is a doc generator in mini.nvim which seems to have a more "well behaved" structure https://github.com/echasnovski/mini.nvim/blob/main/doc/mini.txt. That could be a better one to use, though AFAICT it doesn't support specifying fields in a table arg without creating a new type which is a bit of a pain

[HiPhish]

I have updated to a more recent version (bc2890c) and gO works now. The other two points still stand though. In particular the top of the manual still does not conform to :w help-writing, which means the manual does not show up in the listing on :h local-additions.

I like to keep docs next to where they are relevant and so would have to keep the docs in emmy lua format and in vim help format, which I don't want. I'd rather have a single source of truth.

I fully understand your sentiment and a while ago I had the same problem when I was writing a Common Lisp library. The problem though is that a manual serves a different purpose than a docstring. A manual is written in prose and can provide context beyond the scope of a docstring. It can contain further elaboration, it can describe how the individual pieces fit together. In the end I decided to just copy-paste the docstrings into the manual and add some markup. Yes, it is manual busy work, but generally docstrings change rarely.

I think the best solution would be a templating engine like Jina where you write the actual manual as a template by hand and leave small placeholder snippets. The templating engine then goes through the template, finds the placeholders and fills the necessary data in. The challenge would be parsing out the docstrings from the comments.

[rcarriga]

I fully understand your sentiment and a while ago I had the same problem when I was writing a Common Lisp library. The problem though is that a manual serves a different purpose than a docstring. A manual is written in prose and can provide context beyond the scope of a docstring. It can contain further elaboration, it can describe how the individual pieces fit together.

Totally true, but this is still very easily done with the generators. The reason the current docs don't have a more verbose manual style is that they just haven't been written which is more of a PEBCAK than a tooling issue :smile:

I've made the switch to minidoc in #87 which should address the issues with formatting etc. Let me know if you spot any issue with it.

[HiPhish]

Yes, formatting is fine now. What should we do with the ticket now, keep it open until they other two points are resolved, or just leave it at this and close?

Totally true, but this is still very easily done with the generators. The reason the current docs don't have a more verbose manual style is that they just haven't been written which is more of a PEBCAK than a tooling issue :smile:

In the Python ecosystem there is a library called Jinja in which you write your document (HTML, LaTeX, or whatever else, Jinja does not care) and insert little snippets, then run Jinja on your document and have it substitute those snippets. You can even have variables, conditions and loops inside snippets. This would be a good compromise because it would allow authors to write the prose of the manual by hand and have the generator splice in the API reference. The hard part is going to be extracting the API information from the Lua comment.

[rcarriga]

This would be a good compromise because it would allow authors to write the prose of the manual by hand and have the generator splice in the API reference.

Sorry I don't understand what the problem with the current generator is. We can already write verbose prose alongside the comments. For example in https://github.com/nvim-neotest/neotest/blob/master/lua/neotest/init.lua, though the documentation isn't very long, it still works the same as you describe where there are just blocks of hand formatted text that will be added to the docs by the generator. The bonus being that the docs also live with the module they're related to (if there is one)

Switching to something like Jinja, as you said, introduces the problem of parsing the lua comments. So it adds a problem without solving any AFAICT?

[HiPhish]

Maybe I came off wrong, please let me clarify. A manual consists generally of four parts: tutorial, guide, reference, and explanation. How much emphasis to put on each one and whether you actually need all of them depends on the projects (e.g. you don't need a tutorial for a color scheme). Each of them serves a different purpose:

• Tutorial is for users who just downloaded the thing and need to be held by the hand to get a minimal example going
• Guide explains the different things in plain prose; it assumes familiarity with the entire software but covers individual topic piece by piece
• Reference it the cold hard API and very terse, this is what the user will look up when he know what he is looking for
• Explanation goes deeper into topics, discusses tradeoffs and why certain decisions were made the way they were made

This website explains it quite well and the Vim documentation is an excellent example of these principles. I am not familiar with mini-doc, so I am assuming that this is due to the way generators work, but every generated manual I have seen so far has had the same problem: it is mostly reference with some explanation squeezed in. Right now the Neotest documentation is split between the manual and the README, the last sections of the README is completely missing from the manual.

A prose-first system like Jinja (and I am not saying that Jinja is the best, it's simply what I am familiar with) would allow one to write all the prose in one place, but keep the reference with the code. Because when I read the code or use the LSP hover feature I want to know the function signature, I don't care about all the fluff of how the pieces fit together for the end user.

[rcarriga]

Thanks for the explanation, I do see your point more clearly now!

The tutorial is currently fulfilled by the README. I'm not sure this needs to be in the help file as well so for now I'm happy with how it is. I don't think any plugins I'm aware of have install instructions etc in the help file but could be wrong.

The other parts are currently all mixed in together or missing large parts.The guide and reference are really what is contained in the help file right now but are not separated. Ideally yes there would be a higher level guide that users can skim through without worrying about nitty gritty details.

The only instance of the explanation I believe is the section on adapter writing in the README, and that jumps between guide and explanation based on how you describe them. I wrote that section just before releasing so that people would have some idea of how to write an adapter. I purposefully didn't place it in the help file because it is not meant to be long-living documentation :sweat_smile:

All of that is to say, yes the documentation needs a fair bit of work! However unfortunately using a tool like Jinja won't solve that as the issue isn't with the generator. mini.doc allows for a lot of customisation, and would easily allow for embedding text from separate files, which, as you describe, would contain the verbose documentation not attached to a single point in code.

Right now with how the documentation stands, the current generator more than fulfills the needs. Switching to another tool would just create more friction than anything else (as we'd have to parse all of the comments). I can definitely see Neotest getting to a point where that is not the case though, and a custom generator is used (perhaps integrating a tool like Jinja), but for right now the only thing needed is for the documentation to be actually written :smile:

[HiPhish]

The tutorial is currently fulfilled by the README. I'm not sure this needs to be in the help file as well so for now I'm happy with how it is.

I disagree, but whatever, it's your project. Ideally the help file should be all the documentation there is because it is integrated into the editor, I don't have to browse the file system for a non-standard file. The README should be like the blurb you see on the back of a box, unless the plugin is something really obvious that doesn't need a manual (like a color scheme or a syntax highlighting plugin). I can just open the manual in one window (:h neotest.txt or :h neotest-tutorial) and follow along in another window. I did something like that in the manual of my debugpy.nvim plugin if you want to see what I mean: debugpy.txt

I don't think any plugins I'm aware of have install instructions etc in the help file but could be wrong.

If the installation is trivial then there is no point in having install instructions. After all, if you can read the manual from inside Neovim you have already installed the plugin. I would only consider adding install instructions if there are any external dependency of extra steps needed, but in that case it would be better to provide a health check implementation.

Right now with how the documentation stands, the current generator more than fulfills the needs. Switching to another tool would just create more friction than anything else (as we'd have to parse all of the comments). I can definitely see Neotest getting to a point where that is not the case though, and a custom generator is used (perhaps integrating a tool like Jinja), but for right now the only thing needed is for the documentation to be actually written :smile:

OK, I am not familiar with what mini-doc can actually do, that was a misunderstanding on my part. Do you need help with writing the documentation? I consider myself a good writer, but a terrible reader of source code, so I expect there will be need for correction from you when I get details wrong. I cannot promise to become a dedicated technical writer for the project though, so you must be willing to keep the documentation updated once it is written. Having outdated or wrong documentation is worse than having no documentation.

[rcarriga]

It'd be great to have help writing the docs, I would consider myself a poor writer so it's very much appreciated! I'd absolutely be happy to help with finer details, corrections etc and of course there's no expectation of maintenance once written. I'm happy with maintaining docs, it's just writing the initial draft that takes time. I'd also probably prefer someone else to write it purely because it's easy to gloss over areas without realising due to familiarity.

If you wish to write docs, I'm happy to take a PR with just a text file thrown somewhere and then I/we can work on how to integrate it within the generated docs!

[HiPhish]

Sounds like a plan. I'll try to come up with a PR and then we can discuss the details there. I will close this issue now.