Simon Michael
unread,Dec 11, 2022, 1:16:09 PM12/11/22Sign in to reply to author
Sign in to forward
You do not have permission to delete messages in this group
Sign in to report message as abuse
Either email addresses are anonymous for this group or you need the view member email addresses permission to view the original message
to hledger
>> If it would be helpful for you to have me turn the examples into real postings for any or all of the above, just say the word, and I will gladly do so.
>
>
> In tests, examples, and sometimes docs, I often use minimal data, and a few conventions, like:
>
> - ISO YYYY-MM-DD dates
> - first day of the year
> - no description
> - a b c for account names
> - A B C for commodities
> etc.
>
> This is to reduce mental effort of generating them, and to help the reader focus on the thing being explained rather than incidental details. Also to reduce dependence on the english language.
>
> I think that works for people familiar with the syntax, but I agree that sometimes it can look less realistic, more obscure and offputing to people learning, who don't yet have a solid grasp of the parts of a journal entry, or who haven't learned the (unbalanced posting) notation.
>
> I think we'd like to keep all of these benefits, so it's a tradeoff. Also, while the needs are different for developer tests and for user-facing docs and examples, there is some advantage in using a similar style for both, for ease of re-use.
>
> With that in mind, which of these do you think are worth adopting as preferred policy, in user-facing docs at least ?
>
> 1. using 2+ balanced postings, avoiding unnecessary use of (unbalanced postings)
>
> 2. using realistic account names (english or multi-language ?)
>
> 3. using realistic commodity symbols (single-character symbols or three-letter codes ?)
>
> 4. adding realistic transaction descriptions
>
> 5. drawing examples from a canonical, consistent example journal or set of example journals where possible, to increase realism and save work (producing, updating and keeping examples correct is costly)
>
> 6. ... ?
Cc'ing here, in case others have thoughts. I think I lean towards realish but short data in user docs and examples, and minimal data in tests.
>
>
> FYI I did a read-through of the hledger manual today and hope to do some section rearranging/renaming soonish.
>