On Mon, Feb 8, 2016 at 9:08 AM, John Hendy <[email protected]> wrote:
> On Sun, Feb 7, 2016 at 12:59 PM, Martin Blais <[email protected]> wrote: > > On Sun, Feb 7, 2016 at 11:44 AM, Simon Michael <[email protected]> wrote: > >> > >> We have a lot of docs, in various states of freshness, specific to each > >> implementation. Also many informative blog and mail list posts. Much of > >> this is hard to find. > > > > > > Is it? > > > > > >> Reading Stefano's recent ledger list post, I think, not for the first > >> time, wouldn't it be great if we had all of this linked somewhere > >> central, curated, and presented beautifully, providing an easy on-ramp > >> and reference for newcomers and experts ? Actively maintained by the > >> community ? > > > > > > I keep all relevant docs linked from a single place: > > http://furius.ca/beancount/doc/index > > Everything Beancount can be found there. > > > > I think a few choice threads should be linked from somewhere too > eventually. > > I'm not a huge fan of Google Docs, but I *do* quite like your index > and then having more topic-specific pages. What's wrong with Google Docs? My experience with it is tremendously positive and enduring. The ability to receive comments and suggestions in-line by anyone has been a key contributing feature to increasing the quality and correctness of the text. And it looks terrific on all devices. I have instant access to all past revisions. I can download to various formats, including bake a PDF book. I can process them using the API. I wish it was easier to make the entire text conform to a particular style (separate style vs. contents) but that's mostly an author concern, not a reader. And in comparison to all my other projects, the number of user contributions to the docs has far, far exceeded that which I would have received had I written them in texinfo, ReST, markdown, LaTeX or any other format (and I'm no stranger to those). What I've found is that people who don't like it do so mostly on dubious ideological grounds (the docs are open and downloadable, it's not a walled garden), and partly because it's highly unusual in the OSS community. Are you sure you're not just having an irrational response to something you're not used to seeing? Documentation is difficult to write, and most projects are vastly underdocumented. Google Docs makes it a _lot_ easier to write great docs, and to make corrections, together. It's perfect for open source projects, more should adopt it. > Ledger's docs have the TOC, > but I've found navigating that monolith page somewhat unappealing. I'm > not really sure why as I can still search the page... just something > about being somewhere in the sea of all that text just isn't my > favorite. I rather like Org-mode's documentation: > - http://orgmode.org/manual/ > > It's got a TOC, and sections are further broken down. This also makes > it easy to link someone to a bite-sized page for help, e.g.: > - http://orgmode.org/manual/Motion.html#Motion > > Then there's the user-contributed wiki, Worg: > - http://orgmode.org/worg/ > > There are more "official" pages on using various features, as well as > user-updated link stores for things like "outside" tutorials: > - http://orgmode.org/worg/org-tutorials/index.html > > Anyone can contribute, and even in my ~1 week on this mailing list > I've already seen that there are clearly different ideas of how to > accomplish various tasks. For example, probably 5 folks suggested ways > to handle inter-account transfers (like checking <-> credit card). > These could be put in a user-contributed wiki so that the information > isn't purely stored in a mailing list. The relationship seems to be > that the manual has more syntax/setup information, while the wiki is > more for tutorials and practical usage. If ledger were re-written as > so, I think the "prose-y" stuff about double entry accounting might > live in the wiki, while things like `ledger -f file.dat [options]` > type stuff would be in the manual. Or valid file/transaction syntax, > internals, augmenting with scripts, etc. > Have you seen my cookbook docs? https://docs.google.com/document/d/1RaondTJCS_IUPBHFNdT8oqFKJjVJDsfsn6JEjBG04eA/edit#heading=h.ydun6pj2h2kq Just some ideas from experience with another open source project! > > > John > > > > > > >> If so, where would that somewhere be ? ledger-cli.org and/or its wiki > is > >> the closest existing candidate, but it has never felt right to load that > >> up with non-Ledger stuff. I think it's valuable for each implementation > >> to have its own distinct site. I think a separate, well-named, highly > >> findable site, even a single page collecting all useful links and acting > >> as a portal to the ledgerverse, could be a win. > >> > >> If you agree, what would you call it ? Martin, since you are retiring > >> your LedgerHub tool, would that name be available ? > > > > > > It will be "available," - this just means I'll put a big fat notice on > its > > homepage that it has been swallowed by Beancount - but I wouldn't > recommend > > reusing it, that will just create more confusion, it's a bad idea IMHO. > > > > > >> Related to naming.. what do we call this whole topic, anyway ? Stefano > >> used the phrase "command-line accounting". But we have curses and web > >> GUIs too. "Plain-text accounting" ? Pretty soon we'll probably support > >> some non-text storage format. "Ledger clones" ? Too narrow. Aside: in > >> conversation, I use "ledger-likes" for things similar to but not > >> necessarily compatible with Ledger (ledger, hledger beancount, abandon, > >> penny) and "*ledger" for very compatible ledger-likes (ledger, hledger). > > > > > > Command-line accounting is the most evocative IMO. > > > > > > > >> Any thoughts ? > >> > >> -Simon > >> > >> On 2/4/16 9:41 AM, Simon Michael wrote: > >> > I think we could pick out a few common tasks to focus our > >> > tool-building/documenting efforts on. Eg: > >> > > >> > 1. importing bank data and CSV generally. All of the tools and basic > >> > generic workflows for this should be described on one page. Focus on > >> > CSV, but we should mention OFX too (ledger-autosync is arguably best > at > >> > this with its download feature). > >> > > >> > 2. exporting all data and reports as CSV > >> > > >> > 3. moving data between the ledger-likes (ledger, hledger, > beancount...). > >> > Again, all tools and techniques gathered on one page. All existing > >> > formats should be listed. The output of "ledger print" is a sort of > >> > lowest common denominator, I propose we give it a name and decree that > >> > every tool should import this as a basic interchange format. And/or a > >> > standardised CSV representation of it, such as "hledger print -O csv" > >> > > >> > 4. moving data from and to other accounting tools (gnucash, > moneydance, > >> > excel, quick{en,books}, mobile account apps) > >> > > >> > 5. manual data entry. Editors and their modes, ledger entry, hledger > add > >> > and other prompting tools, hledger-web, recurring entry scripts, etc. > >> > > >> > 6. a catalog of journal entries covering all common transactions > >> > > >> > >> -- > >> 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 post to this group, send email to [email protected]. > >> To view this discussion on the web visit > >> > https://groups.google.com/d/msgid/beancount/d0a1826e-2468-ff82-2984-9cc3afdbab1e%40joyful.com > . > >> For more options, visit https://groups.google.com/d/optout. > > > > > > -- > > > > --- > > You received this message because you are subscribed to a topic in the > > Google Groups "Ledger" group. > > To unsubscribe from this topic, visit > > https://groups.google.com/d/topic/ledger-cli/u648SA1o-Ek/unsubscribe. > > To unsubscribe from this group and all its topics, send an email to > > [email protected]. > > For more options, visit https://groups.google.com/d/optout. > > -- > 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 [email protected]. > For more options, visit https://groups.google.com/d/optout. > -- --- You received this message because you are subscribed to the Google Groups "Ledger" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. For more options, visit https://groups.google.com/d/optout.
