Dear all, I am very glad that I have found beancount, it helps me a lot! However, it also has a steep learning curve for beginners, and I have found myself to study the code at the end to find out how to use it. This is only possible for me because I have some free time left at the moment, most users will want to use beancount in order to save time, not to spend hours in trying to understand it when they should be getting their bookkeeping done, which is already a chore. I think, this is in large part due to issues with the documentation. I am quite proficient in Python, however, I am struggling since one year to completely understand the complete workflow of beancount and are working around by writing scripts for myself that convert CSVs to Beancount format without using any of the Beancount tooling. It seems that several other users are having problems, too [rd1][rd2].
I for myself have the following main issues: 1. Documentation for data import is outdated (beancount.ingest [bc1]), still referring to the old beancount-ingest method, but bean-ingest is not included anymore with the version 3.x published on pip. Moreover, it only provides a full-fledged bells-and-whistles solution, including archiving etc. There is no "simple first step". 2. There is no comprehensive documentation of all functions. The BQL docs [bc2] tell me to use `help from` etc., in `bean-query`. But the documentation there is not sufficient, as the parameter meanings are not explained; for functions like date_bin(str, date, date) or getprice(str, str, date), their meaning is not self-explanatory. There are already proposals to improve it, for example: 1. User "Alen Šiljak" has made several comments and suggestions to the beangulp google doc, which have not been adressed since end of May 2025. I think it would be great if the author could accept them, even if they might not be perfect, they are definitely an improvement. 2. I have proposed extensions to the function documentation in `beanquery`[bq1] which have been criticized for being mostly documentation and not code. So there seems to be disagreement between the google docs and the beanquery project as to where the function documentation actually should live. So it would be great if the maintainers could find some agreement here. In the current state, it was a frustrating experience for me to learn my ways around beancount and it is also frustrating to see such a valuable program being hampered by such issues which remain unsolved despite community efforts to improve it. Could you provide some direction for me what I should do that would be most helpful for you in order to improve the documentation? Best wishes, Moritz [rd1]: https://www.reddit.com/r/plaintextaccounting/comments/182zxe0/absolute_beginner_guide_for_beancount_importers/ [rd2]: https://www.reddit.com/r/beancount/comments/1f5hapm/beangulp_or_ingest/ [bc1]: https://beancount.github.io/docs/importing_external_data.html [bc2]: https://beancount.github.io/docs/beancount_query_language.html#simple-functions [bq1]: https://github.com/beancount/beanquery/pull/263 -- You received this message because you are subscribed to the Google Groups "Beancount" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To view this discussion visit https://groups.google.com/d/msgid/beancount/d15f713e-611a-415c-98d3-92b63f2d1cfen%40googlegroups.com.
