Update html help theme or use a different doc generator to improve help readability

kiteloopdesign commented 2 years ago

Hi,

hledger html help is quite detailed indeed but I think not so much reader-friendly. It is very easy to get lost with all info in a long, single-page html. Personally I always have a hard time navigating through hledger html doc, and quickly get overwhelmed by the sheer amount of information that is presented at once. I think this is an important source of frustration, especially for those getting started with the tool

Not sure what it is used to generate the html help at the moment, but I would use something more standard like "read the docs" theme (available from instance via Sphinx)?

Basically, what "read the docs" (and many others) provide, and what I would expect in order to ease doc reading is:

Split current single huge html page into smaller ones
Use numbered headers and sections so reader knows where and at what level he/she is
All times visible frame with headers/subheaders to serve as navigation index; quickly click on a related topic, rather than scrolling all way up to see the frame
Related to already mentioned, but just to illustrate. Below index needs numbering (and probably lowercase letters)

Combine a number of sections which are scattered around. See

https://github.com/simonmichael/hledger/issues/1862#issuecomment-1110652177

simonmichael commented 2 years ago

Thanks for the feedback and specific suggestions. Our docs are a top priority and have evolved through many iterations. I am of course interested in finding next moves to make things better. Our previous iteration was Sphinx with the read the docs theme. IMHO the current mdbook setup is significantly better than that version overall. Docs have very many aspects to consider, and it is a balance of tradeoffs and many needs; I think it would probably be helpful to discuss in the chat, and I'd be glad to do that. I'm not rejecting your ideas above, but here are some quick replies:

Split large html page into many smaller ones

It's a tradeoff. The hledger manual used to be five manuals, with one for each file format. This complicated maintenance and spread out information in too many places. Now we have one page per manual/hledger tool. Remember that the manual must generate usable renderings in multiple formats, multiplied by multiple hledger versions. The hledger manual in html format is a very large page but it at least has a complete table of contents and it is easy to search all of it and relatively easy to manage multiple versions of it. You could imagine splitting it into very small pages, like a wiki, and that would be interesting to see but there are definite pros and cons to this. Note the hledger manual in info format is split this way, and that does work well for Info users (if those exist).

Number headings and sections

Again it would be interesting to see, and I'm sure I have tried it here and there but I think such numbers are useful only when relatively stable. They would change as we reorganise the docs, and I think it's important that we can reorganise freely. I expect it would also be quite challenging to show consistent numbers across formats and across documentation tools (what works in sphinx won't work in mdbook, what works in mdbook will break in our next docs incarnation, and so on).

Always visible navigation frame (TOC ?)

(Assuming the web docs, again:) We have the always visible overall site TOC on the left (unless someone has the sidebar collapsed). I agree it would be nice to experiment with keeping the page TOC on the right always visible, and I'd love to test that out. I think it's quite a bit of work to do it well. It may consume a lot of useful screen space. It needs to adapt to small screens. It needs to be robust across browsers. Would it react to user's scroll position ? How would it behave when the page TOC is taller than screen, as in the hledger manual ?

Combine related sections which are scattered around

It's not always easy, but I agree there must be lots of opportunities for this. For example yesterday I reduced the number of places documenting scripts from ~3 to ~2. Help is welcome.

simonmichael commented 2 years ago

Also, to help me better understand the problems you're seeing, could you give more details: what docs are you viewing - the hledger manual at https://hledger.org/hledger.html ? Is it mainly this one that's problematic, or also others ? In what web browser and on what screen size ? Could you walk me through some specific doc tasks you're trying to perform and how they go wrong ?

simonmichael commented 2 years ago

PPS I agree that overwhelm is a problem! I find it hard to solve, because for PTA and hledger there is just a ton of necessary information (essential complexity), plus a constant proliferation and duplication of docs (accidental/historical complexity). I have simplified both site and page TOCs, reorganised, rewritten, many times but it's a big project. Fresh ideas welcome!

kiteloopdesign commented 2 years ago

Thanks Simon for your detailed and kind reply

Yes I was referring to https://hledger.org/1.26/hledger.html indeed, should have been more explicit

I hear what you say there and I know its not easy to find the ideal trade-off b/w formats. I am no-one to say what you should do and at the moment I am not interested in working on documentation, so please just take this as a suggestion from a technical user. I come from IT and not from accountancy, and I am quite used to read complex, scattered doc (ASIC design tools I am looking at you) but somehow I am finding it quite hard with hledger (accounting topics also don't seem to help to keep my focus)

Anyway, I think I know now what the main thing driving me crazy is. I see no "scroll/postition slider" on the right side (using Mozilla), and this is a super strange feeling-lost kind of thing in long pages. I just tried on Chromium and it can be seen, though:

Other big thing to me is that the left frame which IMHO brings no interesting navigation is shown at all times, whereas the important one, the one at the right, disappears just after the few lines of the document (it can also be seen on above image).

I would prioritize one of the doc formats and drop the rest? BTW, which ones are those? I guess the classical latex document? I would centralize all the scattered docs into a more central location and use the web as the gold reference. But again, I hear what you say, it is not easy.

Not sure what mdbook is but I guess is some kind of markdown. Markdown is, IMHO, good for few pages on github, but it's too weak to do proper documentation like the sort of things Sphinx-generator can do. There's some alternatives to convert b/w formats as well (pandoc), but I've never really looked into them.

Broken links

https://hledger.org/support.html-feedback

sm1999 commented 2 years ago

Maybe layout like mkdocs-material could solve the navigation and page TOC issue.

kiteloopdesign commented 2 years ago

Nice, didn't know that one, thanks for sharing

On Mon, 25 Jul 2022 at 19:23, Saurabh Mhatre @.***> wrote:

Maybe layout like mkdocs-material https://squidfunk.github.io/mkdocs-material/getting-started/ could solve the navigation and page TOC issue.

— Reply to this email directly, view it on GitHub https://github.com/simonmichael/hledger/issues/1895#issuecomment-1194382444, or unsubscribe https://github.com/notifications/unsubscribe-auth/AEEJHQWZQK6P3SCTC46AJWLVV3ESBANCNFSM54PP5PVQ . You are receiving this because you authored the thread.Message ID: @.***>

kiteloopdesign commented 2 years ago

Let me use this thread to quickly mention two things I would have as useful transaction for people not versed on accountancy. Lending money to a friend

https://www.reddit.com/r/plaintextaccounting/comments/b4avk6/whats_the_best_way_to_book_lending_money_to_a/

https://hledger.narkive.com/t7VvTsBl/how-to-model-unowned-money

simonmichael commented 2 years ago

Not seeing the scrollbar is unexpected. I see it in Safari and in Firefox Devel:

the left frame which IMHO brings no interesting navigation is shown at all times, whereas the important one, the one at the right, disappears just after the few lines of the document

Very true. In the previous iteration, the left sidebar used to have all of the site and current page TOC, readthedocs style. (This is a nice efficient feature of RTD.. but for some it also made the content seem infinite and maze-like, with links appearing and disappearing..)

I would prioritize one of the doc formats and drop the rest? BTW, which ones are those?

HTML, info, man, plain text. For a CLI/TUI program, and with the goal of always-available local docs, I felt the non-html versions are quite important to have.

Not sure what mdbook is

It's a basically a more modern, simpler, faster Sphinx. For maintaining these docs, it has been much better. I have also used pandoc pretty much all along, and still do.

Very helpful feedback, thanks!

simonmichael commented 2 years ago

https://hledger.org/support.html-feedback

Thanks, fixed now I hope.

two things I would have as useful transaction for people not versed on accountancy.

I gather such practical accounting advice at https://hledger.org/cookbook.html#accounting-and-bookkeeping, but lately more at https://github.com/plaintextaccounting/plaintextaccounting/wiki#accounting-situations . I think it needs more of a wiki and a community focus to keep up.

simonmichael commented 2 years ago

Opened related issue #1897.

simonmichael / hledger