I created a command-line interface (CLI) tool for a community project, and while it works well, I've noticed that other developers struggle to understand its commands and options. I'm looking for advice on how to structure the documentation effectively. Should I create a `docs` folder with markdown files for each command? Would wiki pages be a better option? I'd like my documentation to be somewhat automated to avoid it becoming outdated, but I'm unsure how to achieve this given the framework I'm using (Spectre.Cli) doesn't make it very straightforward. What's the best approach?
4 Answers
I’ve seen examples on the Spectre.Cli website that show good usage patterns. If you include Description strings in your command definitions, it helps keep things up-to-date. You might look into the possibility of adding markdown to those descriptions for more detail, but it might be unnecessary if the current setup suffices.
Have you considered creating a man page? I always expect to see a `--help` option for commands. If that doesn't give enough details, I typically check the man page next. That said, if you're aiming for documentation accessible outside of the terminal, then it might be better to create something like a `docs` folder for markdown files to provide an overview of your tool without needing to type commands.
What do you mean by man page? I want my documentation to be more user-friendly, so people can understand what the tool does without having to try anything out.
Always ensure you clearly explain what your tool does and provide some usage examples. That really helps users to understand it better!
What’s the essential info I should include in the README? I don’t want two separate documentation files, but I also don't want it to say just "check X".
You should definitely have a `-help` switch for your commands. It's a standard practice for CLIs to also include a main 'help' command that lists everything, along with more specific help commands like 'help '. It sounds like your tool mainly runs functions itself, so a top-level 'help' command with specific command options is ideal.
That’s great to know! The framework provides some automatic help features, but I want users to be able to see a summary of the tools and commands without installing anything. Having pages for each command might be beneficial.
I would prefer markdown for each command to allow users an easy overview without needing to use `--help` every time. If having only `--help` is typical, I can live with that, but I just want to ensure users can access the relevant information easily.