Docs, where next

[Simon Michael]

G'day all !

I work on the hledger.org docs from time to time. (If you haven't been there in a while, do take a look, to know the current state of things.)

I think these docs are strong and a lot of folks appreciate them. And at the same time I suspect a lot of folks find them "too much", and avoid engaging with them, perhaps even more than is usual.

Here are some related thoughts I had on #hledger chat today:

nobody reads the manual 🚀

and I can't blame them

does anybody wonder what it would be like to dynamite hledger.org and start fresh

writing a new one from scratch would be.. interesting at laast

but if you don't dynamite the site, it would just ends up another duplicatory partial doc

it would be doable to write a fresh guide to the basics. Pretty tough to recreate all the detailed reference info

I wonder how something like this could happen other than a dedicated month in the woods

you could make the manuals the home page, and make the rest less prominent. Or move it to another site

hledger.org - hledger manuals, and install page maybe

wiki.hledger.org - the rest

by manuals I mean 3 pages, the hledger, hledger-ui, hledger-web reference manuals

What are your thoughts ? Do you agree with the problem description above, or do you see others, or do you think everything is fine ?

When docs get large, it requires a sustained focus to maintain and improve them in a consistent way.

Is there anyone out there with suitable time/motivation/skills to form a "documentation task force" with (or without) me ?

What could be some near-term goals of a hledger documentation task force ?

[Simon Michael]

PS for completeness, since it's not linked as prominently as I thought: be aware that there is also the

https://plaintextaccounting.org static site

and

https://wiki.plaintextaccounting.org github wiki

and that I have been in some cases moving content from hledger.org to there when it makes sense.

[niels...@gmail.com]

First, I agree that the documentation is in overall good shape.

I don't have an answer to your questions, but I will throw out some more questions for people to opine on.

Would a change in the documentation be sufficient to cause people who don't read it to start reading it? If so, what would these changes look like? If not, what is going to be most helpful to the people, in terms of profitably using hledger, who don't refer to the docs?

And thinking about documentation in general, what examples can people identify of docs that are useful to people who don't normally use such reference materials?

And my last question is, what additional questions should we be thinking about?

Rob (aka hledger fan)

[Simon Michael]

Great questions!

> Would a change in the documentation be sufficient to cause people who don't read it to start reading it? If so, what would these changes look like? If not, what is going to be most helpful to the people, in terms of profitably using hledger, who don't refer to the docs?

Armchair thinking, ignoring cost: probably more prominent help, tutorials, support links/chat built in to the software, more work on error messages, built in templates/examples...

Marketing activity: regular news/tips posts, mastodon posts, scheduled txt/a/v chats/livestreams, podcasts, videos...

GUIs, which make features more discoverable and which are more motivating for many folks.

More visual appeal generally. (Screenshots, colour, charts..)

Prominent testimonials, compelling success stories and case studies.

... ?

[Michael Semple]

I am a new, circa 1 month, evaluating user, so not really qualified to provide you much feedback… except to say, perhaps, that I have found the documentation, including the user manual, very useful and refer to it all the time.  It‘s popular bedtime reading at the moment.

However, it is still a big challenge to learnt it all.  And since I really liked the „full-fledged“ user example, I’m working at that approach.  But it’s a big effort also because I need to refresh/progress my shell scripting/sed/awk skills too, and figure out what is easiest with sed/awk/hledger rules etc.

I currently use YNAB (3 years) and have learnt a lot from following it’s budgeting principles, so am trying to setup similar practices with hledger.

I tried in the past, perhaps 10 years ago, to start using ledger.  But didn’t get as far before giving up.  I didn’t have as much time on my hands, though.  But the hledger manual and pta site‘s examples were a reason for me to try again.

If I figure out anything concrete, I‘ll be back.  But in the mean time, thank you ever so much!!!

Mike

[Simon Michael]

Thanks Mike, all useful to hear

--
You received this message because you are subscribed to the Google Groups "hledger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to hledger+u...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/hledger/c1ddf2c5-9b12-4ce7-9be6-0a2da88dac30n%40googlegroups.com.