On Wed, Feb 10, 2016 at 1:48 AM, Dominik Aumayr <[email protected]> wrote:
> As a member of the beancount community I can see how Google Docs has huge > benefits in the practical world: > > - WYSIWYG > - Editable by everyone with an account > - Changesets > - Inline-comments > - It feels like a document, not a website (altough this is not always a > benefit) > > And I also get why people might want something else, having just started > worked on a new starting-point for the beancount documentation (based on > Sphinx; http://aumayr.github.io/beancount-docs-static/): > > - Ideological reasons (Google is evil for [some|many] people in these > communities) > That's a very difficult argument to make. > - What if Google Docs goes away? Exporting the content is a feature, but > then manually converting the content to fit a new system would be neccesary > anyway. - Navigation is a pain IMHO (missing sidebar-menus, etc.) > That could indeed be better, but other than the sidebar and the fact that's it looks familiar to Python users (which arguably aren't necessarily the typical Beancount user), and other than the sidebar, how is this: http://aumayr.github.io/beancount-docs-static/users/index.html substantially different or better than this? furius.ca/beancount/doc/index I'm not dissing on your effort BTW - I like quite like it and I'll integrate it - but rather I'm using it to point out that they're both pages with links and that they're similar. They look different, but they pretty much have the same content. I understand it doesn't look familiar, but ask yourself: is it just a matter of people having to get used to something new, or is there any real substance to that difference? If you were focused exclusively on the rendering, you'd be overlooking the most important part of this: it's a dynamic and collaborative experience. It's a living process. It makes it trivially easy for anyone, with or without an account, with or without programming skills, to update the content and collaborate with me on it, in-context. To pop in a correction for a wrong number (so many corrections so far!). To reword a phrase poorly constructed (thank you readers!). The experience is substantially distinct and better than a wiki as well, especially if you have non-technical readers. Comments and suggestions are treated differently than content, and integrated with a notification system via email. There's no awkward syntax to learn. Even technical users have a difficult time keeping wikis up-to-date! I'm witnessing it daily, both in the OSS world and in the commercial sphere. Maintaining up-to-date docs is REALLY difficult for engineers. Here ... well you just make the edit right there in front of your eyes as you notice something that needs a change and an email is automatically sent to the author. Now, a reader shouldn't care what technology I use to write the documentation. That's the author's problem. A reader should worry about whether the documentation is readable, well-written, understandable, usable, available where they need it to, indexed, cross-referenced, etc. As a potential contributor, in theory there's the offline editing problem, but in practice, most of the docs are written when you're online anyhow. You can write the text in Emacs and import it later on when you reconnect if you're stuck on a flight or a train, as John mentions (how often does that happen anyway?). The actual typing is not what takes time at all--it's the thinking and the re-reading 20 times and re-writing and correcting and looking up definitions that takes time and effort. Cut-n-pasting from Emacs anywhere takes me one second. That's what I do for the few times I happen to write offline, and it's not a big hindrance. But at the heart of this thread there is a subtle disconnect: I think most people on the list are focused on the ARTIFACT, and not on the PRODUCT. There is a similar problem in discussions around computer languages, where people are focused more on whether the language makes it easy for them to write the code over whether the language makes it easy to write "excellent software" without bugs; but... what matters is the product, not the code. No user will ever look at your app and say: "oh, that must be written in a really nice looking language." Here, the task at hand is this: "TO PRODUCE GREAT DOCUMENTATION." That's the job description. The "artifact" is the tool that you use to write the software. It's markdown vs. reStructuredText vs. TexInfo vs. LaTeX. It's Emacs vs Vi vs WYSIWIG. The "product" is the final document that you read. It's the thing on your page. I maintain that what matters is the document; not the data format. No reader will ever look at crappy text and say "Oh, that's unclear, incomplete and confusing, but at least they made the effort to write it with LaTeX, that's really nice." Part of the problem is that us nerds are attached to our tools. We've come to believe that our Open Source ways always provide the best outcome. The demise of Windows for much of the internet's piping has proven us right about clinging to some variant of good old UNIX for so many years. We're selfishly focused on our own experience making the docs, not on the resulting document. And in this instance our Open Source ways becomes just another kind of box that we need to think ourselves out of. I understand the other side of this argument, and the desire for writing it all in text files, I've been in love with that. I get the aesthetic. I'm trying to make a different point here, to break out of that mold, to make something new and hopefully better. And I've tried a different way, and my findings are that it's paying off tremendously, not in making my own experience better, but in producing a better result. I think the result speaks for itself. So... what tool allows me (and you) to produce the best possible documentation? Make yourself open to all possibilities for a moment: What attributes of this tool are needed for us to write great documentation? At the top of the list is ease of publication and collaboration. Why? Because when it comes to writing, we're very very lazy and *nothing* beats clicking on the word right there and changing it in place and having the result published instantly, and integrating suggestions and corrections from readers with a single click. Whatever tool makes that process easiest is extremely valuable to an author. Implementing a new documentation system with WYSIWYG, Changesets, an > Inline-comment-feature, but also easy navigation, search and syntax > highlighting is an option, too. > I'd be willing to work on it, if consensus is reached that this would be > the best option. > Okay, just to be clear, I'm not saying that you have to use Docs for your own docs effort; I don't care about that. I'm not a big consensus seeker either (consensus yields average results). I'm saying that it's irrational for people to complain about Docs all the time - as it occurs time and time again either or my list, on private email or on other lists. It's a misguided criticism of a tool that provides a profound improvement to a process that is particularly difficult for us: WRITING. Docs is a really great tool for OSS projects. If you care about the result, you should want to use it. -- --- 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.
