Thanks to the work of Kirill Goncharov (and Dominik Aumayr's predecessor static codebase reference) the conversion of Google docs to HTML via Markdown works quite well. The final product is really slick: https://beancount.github.io/docs/. I think in terms of documentation this is the sweet spot I was hoping for: sources in gdocs that makes it possible to just go to a doc and start typing immediately (zero overhead to make fixes or rewrite portions), and for anyone else to insert a comment or suggestion, but with an output familiar for an open source project (familiar web pages with text). What we trade off for changes managed via commits and the associated history, we gain in collaboration and much more resultant documentation (I never would have written this much otherwise).
As part of the Github migration, another thing I'd like to change about the documentation eventually is the conversion of links between Google docs from redirects through my website furius.ca, to use some other more permanent means of redirect. The history of it is that began to write the docs I wanted to have a way to refer to them by name, and the Google docs addresses aren't memorable (they include a long auto-generated "document id" root at docs.google.com/document/d/). I created a redirect configuration rooted at http://furius.ca/beancount/doc/<name>. This way I could send links that were more or less self-explanatory and that I could remember, with a well-known public name (e.g., http://furius.ca/beancount/doc/install), I would just type them in without having to look them up while writing an email. I pretty much consistently inserted such a link at the top of every one of the documents below the title. This would also allow me to change which document an existing link points to, a capability I did not have to use very often, but which was handy the few times I rewrote some of the documents, e.g. http://furius.ca/beancount/doc/export. Overall the system works well. Here's the problem though: my website is generously hosted by friends in their web design & development company. Occasionally - several times per year - there's a network configuration change or an outage and my server is inaccessible, sometimes for 1-2 days. This means the links also aren't resolvable (the server can't respond with a redirect) and if you're reaching the docs through an email thread or on the Google docs source, the links simply won't resolve. This isn't great. In Kirill's HTML conversion the links look like they have been mapped: https://github.com/beancount/docs/blob/master/index.json so they link within the generated site, but it would still be nice to be able to send links by name and not rely on e.g., the generated names of the markdown files. I'd like to move the link root over to something hosted at Github so the docs aren't reliant on my server, the future of which is unclear (I don't have plans to remove it but I don't really need it either). I wonder if it's possible to create redirects rooted at something like http://beancount.github.io/<name>, http://beancount.github.io/docs/g/<name>, or something like that. Maybe there could be a mapping to both the gdocs or the markdown generated docs with the same name, e.g.: http://beancount.github.io/docs/g/export -> https://docs.google.com/document/d/1mNyE_ONuyEkF_I2l6V_AoAU5HJgI654AOBhHsnNPPqw/ <https://docs.google.com/document/d/1mNyE_ONuyEkF_I2l6V_AoAU5HJgI654AOBhHsnNPPqw/edit> http://beancount.github.io/docs/m/export -> https://beancount.github.io/docs/12_exporting_your_portfolio.html Given the scope this project has taken, I could even register a short domain name for this purpose (e.g. beandocs.io?). This is just an idea. I know how to do this on an Apache web server. But can it be done on something hosted at Github? -- 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 view this discussion on the web visit https://groups.google.com/d/msgid/beancount/CAK21%2BhNEPoZCVJDgkRatT7LWhLwOHW1_OXUut1KAJGuMpt%2BRyQ%40mail.gmail.com.
