lsrdg/tatoeba-karini

Built-in documentation

Opened this issue · 2 comments

lsrdg commented

Considering the many different use cases, tools and ways of achieving the same result, a built-in documentation is necessary.
It should:

  • be accessible locally and offline
  • it should be concise (cheat sheet style)
  • ..but it should be as verbose as needed, plenty of examples
  • needs to be searchable, as well.

It might sound too much for now, but if the projects ever passes the v0.1.0 milestone there will be more built-in features than a user needs to remember, but might use occasionally.

lsrdg commented

I would like if Tatoeba-karini could a have a "smart docs", maybe just well handled exceptions that would print out the proper doc page. The targeted user group are not necessarily programmers, just curious people tech-savy enough to dare to touch the command line.

However, this behavior of "action>error>doc" can be handled individually, as each command gets improved (v0.0.7, v0.0.8).

After all, this issue will be closed when:

  • there is a wiki (done.)
  • argparse built-in help is readable (#41 )
  • manual.md is ready (#42 )
  • the README is able to get the user started with the docs (#43 )
  • the wiki is able to handle extra gaps on the docs (#43 )
  • README, Manual and Wiki should play nice together (#43 )
lsrdg commented

There is no built-in documentation. But there is documentation. The wiki can be cloned and there is a manpage. With the changes on argparsing, --help gives a way cleaner help message.

Time to move on. The docs will be kept updated (so that there won't be any troubles on documenting, but only on writing the code).

Despite of the previous comment this issue won't be closed now, but moved to a future milestones.

At some point, it would be great if the script could make use of curses in instead of print()s, and the builtin documentation could be there.