How to update the documentation and make it more beginner-friendly

[M Lell]

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

[Glader]

Look at https://lazy-beancount.xyz/

чт, 11 дек. 2025 г. в 14:47, M Lell <mle...@gmail.com>:

--
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 beancount+...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/beancount/d15f713e-611a-415c-98d3-92b63f2d1cfen%40googlegroups.com.

[Martin Blais]

- There's just not a lot of time, that crazy AI explosion going on all around us... that's where I'm spending time for the past 10 years and it doesn't look like it's abating

- One future day soon enough I'll have some years off and will have another go at all those v3 ideas

Sorry if the docs are out-of-date, read the mailing-list and source for now.

Maybe one day we can get the AI to review all of it and make it up-to-date

--

[Chary Ev2geny]

On Thu, Dec 11, 2025 at 6:47 AM M Lell <mle...@gmail.com> wrote:

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.

 

Do you refer to this document?

https://docs.google.com/document/d/1O42HgYQBQEna6YpobTqszSgTGnbRX7RdjmzR2xumfjs/edit?tab=t.0

May be I am looking somewhere else, but I do not see any comments from "Alen Šiljak" .

 

[mle...@gmail.com]

On 12/15/25 11:06, Chary Ev2geny wrote:
>
> Do you refer to this document?
>
> https://docs.google.com/document/
> d/1O42HgYQBQEna6YpobTqszSgTGnbRX7RdjmzR2xumfjs/edit?tab=t.0

No, I was referring to this:
https://docs.google.com/document/d/1hBfsHZcoHgz5rvhCdP42g2FJ5ouycIMV4H1tfgXpwBU/edit?tab=t.0#heading=h.gmhz8vh65l8g
, which gets auto-converted to the mentioned
https://beancount.github.io/docs/importing_external_data.html

Best wishes, Moritz

[Chary Ev2geny]

On Monday, December 15, 2025 at 11:10:48 AM UTC+1 mle...@gmail.com wrote:

No, I was referring to this:
https://docs.google.com/document/d/1hBfsHZcoHgz5rvhCdP42g2FJ5ouycIMV4H1tfgXpwBU/edit?tab=t.0#heading=h.gmhz8vh65l8g
, which gets auto-converted to the mentioned
https://beancount.github.io/docs/importing_external_data.html

Best wishes, Moritz

Ok, thanks! Unfortunately I do not see suggestions, as I only have a viewer permissions.

Google docs is a great tool, but unfortunately it has annoying limitation, that only commenters / editors can see the work and progress and only those with edit rights can see the revision history.

 

[mle...@gmail.com]

On 12/15/25 11:54, Chary Ev2geny wrote:
>
> Unfortunately I do not see suggestions, as I only have a
> viewer permissions.
>

I think that you can feel free to request access via the button in GDocs!

[mle...@gmail.com]

If you want to improve the docs, I am currently working on a Fava PR
about the same topic which can serve as a blueprint:
https://github.com/beancount/fava/pull/2155

~Moritz

[Chary Ev2geny]

Thanks for pointing to you fava PR

I don't use Fava, so I have a question: have you also added suggestions to correct the beangulp document ? (I requested a commenter access to it now)

https://docs.google.com/document/d/1hBfsHZcoHgz5rvhCdP42g2FJ5ouycIMV4H1tfgXpwBU/edit?tab=t.0#heading=h.gmhz8vh65l8g

I see, that through the pain and spent time you built some understanding of the beangulp as well as what is missing in documentation, so I really want your knowledge to be dumped somewhere (preferably in the original documentation) 

Please do not disappear!

P.S. my personal interest: it is still on my todo list to understand importers tools, so I want it to be well documented. And yes, I do want beancount community to grow (even in case Martin never gets time to to work on V3)

[mle...@gmail.com]

On 12/15/25 12:51, Chary Ev2geny wrote:
> I don't use Fava, so I have a question: have you also added suggestions
> to correct the beangulp document ? (I requested a commenter access to it
> now)
>

I plan to first get the fava PR accepted by creating a documented
example which passes a unit test as requested by the maintainer. From
there, I will make some suggestions to the GDoc. I plan to do so this
week, let's get this sorted together :-)

[Martin Blais]

On Mon, Dec 15, 2025 at 5:54 AM Chary Ev2geny <char...@gmail.com> wrote:

Google docs is a great tool, but unfortunately it has annoying limitation, that only commenters / editors can see the work and progress and only those with edit rights can see the revision history.

It sucks either way.

It sucks less this way.

[mle...@gmail.com]

On 12/15/25 12:51, Chary Ev2geny wrote:

> want your knowledge to be dumped somewhere (preferably in the original
> documentation)

With the PR in Fava currently I am fighting the linter[1] but you can
install the unstable dev version from my repo to have a first look (Menu
Help > Import)

pip install "git+https://github.com/mlell/fava@dev_import-help"
fava <your beancount file>

Cheers,
Moritz

[1]: https://github.com/beancount/fava/pull/2155

[Joshua Cabrera]

I may be way out of my depth here - have you considered making the documentation part of the repo instead of a separate channel like Docs?

[Chary Ev2geny]

Moritz,

in my experience Martin was always accepting suggestions for document changes. But I have put them as a specific wording changes, not a generic comments ("e.g. I do not understand this"), as otherwise I suppose there is too much work to implement comments.

However if there are too much of suggested textual corrections from your side, I guess an alternative approach could be to just create an own fork of the google doc, and put updates there. 

Google docs does not have a feature to merge one document into the other, but it has a feature to compare 2 different documents, which creates a 3rd document with tracked changes (tools => Compare documents). These changes one can then accept or reject individually. One challenge here is that this 3rd created file will obviously have a different file id, hence all existing links will not point to it. But I have tested, that programmatically it is possible to export one google docs file and load it as the latest version of another file, thus preserving the id of the latter (this is example of the code, which does it).

Just thinking aloud,  may be, taking into account the limited time availability of the beancount BDFL, if a fork of the master document is created, then may be it can be maintained as a community version of the document going forward and then Martin can chose to get its changes into the master document, when the time permits.

Martin, what do you think?

On Monday, December 15, 2025 at 11:10:48 AM UTC+1 mle...@gmail.com wrote:

[M L]

Am 16. Dezember 2025 16:37:26 MEZ schrieb Joshua Cabrera <josh.d....@gmail.com>:
>I may be way out of my depth here - have you considered making the
>documentation part of the repo instead of a separate channel like Docs?
>

Google Docs was chosen to provide WYSIWYG editing without the barrier of knowing how to navigate GitHub -- i.e. to be accessible to non-programmers: <https://beancount.github.io/docs/#about-this-documentation>

[Joshua Cabrera]

Thanks for pointing that out. I had forgotten about that, and rereading it now, Martin made it pretty clear with "I have already received orders of magnitude more feedback on documentation than on any of my other projects; it works."