On Mon, Feb 8, 2016 at 8:41 AM, Martin Blais <[email protected]> wrote: > 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?
Sorry for the delayed reply -- busy week! > 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). Very good points, and ones I hadn't initially considered but definitely buy. Org-mode's manual is in texi, and its wiki is in Org-mode format, both managed via git. I admit that as simple as edits are objectively, the simple act of pulling, changing, and pushing is barrier enough that I don't act as often as I could. Some of it even comes down to idiosyncrasies of texi that I didn't know (two spaces at the end of every sentence... or is it line?). In any case, I can see the user-contributed changes/suggestions thing for sure. > 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. No, I'm not totally sure it's not just "different," and good question. That said, some things come to mind. - While I haven't used docs much for actual docs (usually just where .doc[x] files people email me end up when downloaded on my phone), I've used things like google drive and don't like the urls. Maybe that's silly, but it's just cleaner. I just find something nice about the link telling me *something* about the content. Compare: --- Docs: https://docs.google.com/document/d/1dW2vIjaXVJAf9hr7GlZVe3fJOkM-MtlVjvCO1ZpNLmg/edit#heading=h.2ax1dztqboy7 --- Hypothetical: https://furius.ca/beancount/manual/beancount-vs-ledger - Perhaps again silly, but I don't know why the documentation always opens in editing/suggestion mode. I keep freaking out that I've bumped a key and it's suggested something to you when I didn't even realize it was doing so. - Similar to links, Docs don't convey any sense of being related. I guess I'm 3/3 of perhaps insignificant dislikes, but I just don't like that there's no way to know two docs are related. Google Sites had that (same domain). - When I've used Drive to host some PDF and linked to it from my blog, I *swear* the link changed if I changed the sharing settings on the doc. Then I'd have to track down and update the gobbledy-gook links. - On the subject of links, docs seems to assume the same thing you think should not be assumed by ledger: user diligence/perfection. What if you delete/move/rename a page? Docs assumes you will perfectly track down every instance of that link an replace it with the new one.[1] Other systems have automated ways of updating the TOC, creating a hierarchy, etc. and the pages are all known so grep or sed changes seem fairly straightforward. Your doc collection may be pretty manageable at this point, but I can imagine a large number of documents where link management would become pretty annoying. - I'm coming from doing 90% of my document generation via Org-mode, but I would rather type in markup and define systematic formatting than constantly fiddle with italics, bold, numbering, etc. You already hinted that this was a limitation of docs, so I don't think it's worth saying more about. - I really don't care that much about the OSS vs. not argument. I don't pay for github repos... if they decided to shutdown, I'd be stuck without hosting and have to move things. If Docs went down, it sounds like there are ways to get your stuff, so I don't think that argument is super strong. As long as the *format* isn't proprietary, no big deal in my mind. Anyway, I seriously meant that as a super in-passing comment (akin to "I like Colgate more than Crest"). I really didn't mean to get into or start a doc war! Wouldn't a community wiki have all of the advantages of Google Docs as well as some further advantages others are mentioning? It seems like what you like the most are: - encouraging community edits (low barrier to a user suggesting/editing) - edits digestible in some easy way (appear in-line, or similar) - exportable to various formats - revision tracking Is that reasonably accurate? Thanks! John [1] I wasn't aware of some of the features you mentioned in other replies, so maybe it's easier than I know to quickly hunt down changed/deleted links? > >> >> 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 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 "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.
