From 1eb62f58aa652271b7b4e16be529c396882429f4 Mon Sep 17 00:00:00 2001 From: scoobybejesus Date: Sat, 21 Sep 2019 18:11:26 -0400 Subject: [PATCH] Improved documentation. --- README.md | 47 +++++++++++++++++++++++++++++++------------- examples/examples.md | 15 ++++++++------ 2 files changed, 42 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index eb061f5..fcab850 100644 --- a/README.md +++ b/README.md @@ -2,27 +2,23 @@ ### Accounting library for cryptocurrency transaction activity. -###### (Currently runs as a binary, not a library) +###### (Currently runs as a binary) The software measures one's cryptocurrency activity (i.e., denominates one's income/expenses/gains/losses) in their home currency. The default home currency is USD, but anything can be substituted. -This type of tool may be useful, for example, when preparing to file taxes. - -The software has been tested on Mac and Linux. -Testers/users are encouraged and welcome. +This tool is probably most useful when filing one's taxes. --- -Given an input CSV file reflecting the user's entire cryptocurrency transaction history, the software will: +Given a [CSV input file](https://github.com/scoobybejesus/cryptools/blob/master/InputFile_CSV.md) +containing the user's entire cryptocurrency transaction history, the software will: * assign cost basis as of the date of purchase/exchange/receipt * track the original acquisition date and cost basis until the time of disposal * compute gain or loss from the sale/exchange/disposal (including whether short-term or long-term) * record income for incoming transactions and expenses for outgoing transactions -Read up on the [CSV input file](https://github.com/scoobybejesus/cryptools/blob/master/InputFile_CSV.md). - -Reports may be exported as CSV and/or TXT files reflecting income/expenses/gains/losses or amount and cost basis of existing holdings. +Reports reflecting income/expenses/gains/losses or amount and cost basis of existing holdings may be exported as CSV/TXT files. --- @@ -36,18 +32,19 @@ Reports may be exported as CSV and/or TXT files reflecting income/expenses/gains #### Constraints -* *All* cryptocurrency-related activity for the user generally must be included in the input CSV file. +* *All* cryptocurrency-related activity for the user generally must be included in the +[CSV input file](https://github.com/scoobybejesus/cryptools/blob/master/InputFile_CSV.md). * There can only be either one or two accounts used in a given transaction (i.e., if a Counterparty token or Ethereum token transaction must be recorded, the XCP or ETH transaction fee must be reflected in a separate transaction row). * Manual adjustments may need to be made to the output files in cases, for example, -when the user used aprpeciated cryptocurrency to make a tax-deductible charitable contribution. +when the user used appreciated cryptocurrency to make a tax-deductible charitable contribution. ## Installation -1. `cargo build` (or include `--release` for a non-debug build) +1. `cargo build` (include `--release` for a non-debug build) This will build `./target/debug/cryptools` (or `./target/rls/cryptools` for a non-debug build). @@ -62,17 +59,39 @@ or jump directly to the [examples.md](https://github.com/scoobybejesus/cryptools ## Development state -As of summer 2019, the code is "feature complete" in the sense that it does not require additional features in order for it to serve the needs of the original author. -At the same time, there are plenty of bells and whistles, creature comforts, etc. that may be added at any time. +As of summer 2019, the code does not *require* additional features in order for it to serve the project's founder. +At the same time, there are plenty of bells and whistles, creature comforts, etc. that are desired and may be added. Additionally, the code could use factoring or general re-working in several areas. In fact, it may be nice to use the business logic as a library instead of running a full binary. +The software has been tested on Mac and Linux. +Additional testers/users are encouraged and welcome. + ## Contributing * Contributors welcome. New authors should add themselves to the `AUTHORS` file. * Roadmap and todos: we're working through items in [Issues](https://github.com/scoobybejesus/cryptools/issues); feel free to tackle or add issues. +## A few words from the founder + +I have an accounting background, and I live in the US. +I took an interest in cryptocurrency in 2016. +When it came time to file my tax return, I had to come to grips with recording my cryptocurrency activity. +I initially used a spreadsheet to manually process the activity into lots, and it quickly became clear that I needed a software solution. +Given my background, I had certain expectations about what this type of software would do, and I tried several online options. +I eventually created this project as a reaction to the inadequate tooling I found online. +Sure, other products have more bells and whistles, but at least I know this produces correct results +(i.e., this software specifically identifies and track all acquired assets, whereas online solutions seems to pool them together). + +I am not a formally trained programmer, however I enjoy it very much and learn more whenever I can. +I originally tried to learn C++ by myself, and that was frustrating. +My first real progress was with Python, but I still didn't manage to fully develop a working program. +Luckily, I managed to stumble across a mentor who helped me write 80% of an MVP in strongly-typed Swift. +We coded our way into a corner, but I had learned enough to take the code apart and put it back together correctly and complete it. +I really enjoyed Swift, but I wanted something even more performant (and cross-platform), and Rust seemed to fit the bill. +I rewrote the code in Rust (also with a bit of help from my mentor), and it has turned out to be a great choice. + ## Legal See LEGAL.txt diff --git a/examples/examples.md b/examples/examples.md index 830c55d..64ae4ee 100644 --- a/examples/examples.md +++ b/examples/examples.md @@ -11,7 +11,7 @@ The sample input files and the resulting reports are in the `/examples/resources (Note: new reports have been added since the write-up below was written. Nevertheless, evaluating the reports should mostly be self-explanatory.) -## Using the wizard +## 1. Using the wizard ##### First, preview the input file `faker1__sample_input.csv` in your editor/viewer of choice. @@ -26,7 +26,8 @@ Enter the following: Running the command above takes you through the wizard. -     (Note: You can simply run **`cargo run`** instead, in which case after answering yes to "Shall we proceed," you will have to enter the path of the input file.) +     (Note: You can simply run **`cargo run`** instead, +in which case after answering yes to "Shall we proceed," you will have to enter the path of the input file.) ##### Type `` to accept default responses to the first three prompts, which are: @@ -48,20 +49,22 @@ The reports should match those in the `examples/resources` directory. (Additional reports are created too, but you can generally match the existing reports by title.) -## Skipping the wizard +## 2. Skipping the wizard Let's run the program again. This time around, we'll pass command-line parameters to skip the wizard. ##### Again, preview the input file `faker2__sample_input.csv`. -You'll see it's similar to the README example, except that there is a wider variety of transactions, plus the memos are more descriptive. +You'll see it's similar to the README example, except that there is a wider variety of transactions, +plus the memos are more descriptive. ##### Run **`cargo run -- --help`** to see descriptions for the parameters we can use, or just enter: #####     `cargo run -- -a -o ~/Documents ./examples/resources/faker2__sample_input.csv` -    \* Substitute `~/Documents` with your desired output directory. Substitute a Windows-style file path, if necessary. +    \* Substitute `~/Documents` with your desired output directory. +Substitute a Windows-style file path, if necessary. ##### Again, the program runs, and you should have reports in the location you provided. @@ -118,7 +121,7 @@ Also, there is a coffee mug purchase and a donation. The details are easily found in the memo field, but it is up to the user to "parse" those items for their use. * As noted in the README, adjustments occasionally may need to be made to the output reports. For example, in `faker2`, a donation was made. -You may choose (or your accountant may decide) that this transaction (#11) is analogous to donating an appreciated security. +Your accountant may decide that this transaction (#11) is analogous to donating an appreciated security. In that case, you may decide to manually adjust the **Proceeds** to match the **Cost basis**, and then update the **Gain/loss** to be zero. * You can't spend or exchange something that you don't have.