Completely agree with Martin about non-technical users and ease of edits. To add some more thoughts from our experience using Wiki at Dgraph: https://wiki.dgraph.io
- The amount of work required to submit a change to Wiki is **considerably lesser** than doing the same on Github. Consider this, you're consuming the documentation in a browser. You see an issue, if you're logged in, you'll see an edit next to the section, which you can click, fix the issue, and submit. The Github flow is, OTOH, designed not for quickly updating documentation, but for writing code. You switch away from browser; do a git clone or a git pull, do the mod in the entire doc (no section level edit), commit, create a PR, wait for it to be reviewed, address potential issues with the PR, and then wait until it gets submitted. The process complexity is the same whether it's a minor edit or a major one. The result is that Github flow isn't done by most consumers of the documentation. The smaller the edit is, the more neglected it would be. - Wiki formatting is slightly inferior to Markdown but isn't much different (the existing Texi is considerably harder to follow). So, the learning curve isn't all that much. Minor edits wouldn't need to worry about this anyway -- you just see what's around, and follow. - And this is where Wiki really shines -- that is templates. You see a section which is incorrect, needs work, out of date, or want to have a special note, add a warning; you can add a special highlighted box in Wiki. That adds a real value for the end user. No other solution does that -- Google docs or Github. Case in point: https://wiki.dgraph.io/Beginners_Guide . Templates are particularly useful for users who don't know how to fix the issue but can add a "needs fix" template in the right place in the documentation to let everyone else know that there's an issue here. This is a much better solution than using Github issues because you can see the issue when reading the documentation -- they're in the same place. You'll probably still need Github issues, but they'd be for major doc issues. So, what do you give up by moving to Wiki? I'd say nothing really. A one-time script can convert the Texi format to Wiki Syntax. What new things it would bring? All the above; particularly ease of edits and templates. On Sun, Dec 18, 2016 at 7:17 AM, Martin Blais <bl...@furius.ca> wrote: > On Sat, Dec 17, 2016 at 8:20 AM, Brian Exelbierd <b...@pobox.com> wrote: > >> On Sat, Dec 17, 2016, at 01:39 PM, Manish Rai Jain wrote: >> >> Thanks! That definitely helps. >> >> I think the documentation needs updating (documentation being one of my >> main gripes with ledger). I'd suggest a solution: Host the documentation on >> wiki, which would allow community to build and keep the documentation up to >> date. Issues like these for e.g., could be easily marked by the user as >> "not working", and then updated by someone in the know-how with the right >> instructions. That collaborative effort on documentation is the only way to >> keep high quality and easy to understand documentation. >> >> >> We don't need a wiki (even though we do already have one), we have >> something much better. Git. >> > > *giggles* > > > You can submit a pull request on GitHub here: >> >> https://github.com/ledger/ledger/blob/next/doc/ledger3.texi#L7734 >> >> You can track this as a problem by opening an issue there as well. >> > This way everyone keeps everything in one place. >> > > You really don't get collaboration. For tech nerds who are already heavily > involved in submitting changes to a project, that's a logistically superior > solution, in theory. The problem is that it leaves out most potential > contributors to documentation fixes or even just pointing out a sentence or > paragraph they might not understand. For either non-tech users, or users > who have never submitted changes to the project (or filed a pull request on > github for that matter, keep in mind most users' knowledge of git extends > to about two commands: git clone and git pull), that's just not going to > happen. I'd go even further: even if one's able to make the pull request, > the amount of trouble to go through is a threshold that most people don't > bother crossing. I certainly would have better things to do with my time > for a one-liner fix. > > Let me spell it out: > > The easier and quicker non-technical people are able to contribute to > documentation, the more they will. > > A system that would let a user highlight, then click, then type, then be > done with it would be ideal (e.g. Google Docs). A wiki is a slightly > inferior alternative - users have to at least learn some syntax and wade > through some of the source document - but a good compromise nevertheless. I > think Manish has the right idea. > > > > >> regards, >> >> bex >> >> >> For starters, the wikia service could be used (to avoid the pains of >> setting up our own): >> http://www.wikia.com >> >> >> On Sat, Dec 17, 2016 at 10:07 PM, Brian (bex) Exelbierd <b...@pobox.com> >> wrote: >> >> >> > On Dec 17, 2016, at 6:16 AM, Manish R Jain <manishrj...@gmail.com> >> wrote: >> > >> > I'm trying to build a budget, following section 9 in the manual. >> > http://www.ledger-cli.org/3.0/doc/ledger3.html#Budgeting-and >> -Forecasting >> > >> > This command is mentioned in the doc to help determine the average >> spending per expenses category. But, when I use it, the numbers are out of >> whack. They're way too low. >> > >> > $ ledger -p "this year" --monthly --average balance ^expenses -f >> journal.ldg >> > >> > I've tried other variations like using reg, or setting -b flag instead >> of -p. But, doesn't seem to work. >> > >> > Any ideas, what's going wrong? >> >> I was literally doing this yesterday as well. I had the same problem. I >> "solved" it by doing the math manually. >> >> $ ledger -p "this year" balance ^expenses -f journal.ldg --amount "amount >> / 11.5" >> >> As I understand this redefines the amount displayed to be the original >> amount / 11.5. I chose 11.5 because we are approximately that far through >> the year. >> >> Let me know if that gives you logical values. My transactions are in >> about 12 currencies so I'm having trouble verifying them logically. >> >> This is also exposing a need for me to think about journal organization >> as some of these values are "polluted" with data that shouldn't be counted. >> I did conversion of data only back to 2016-01-01. The pollution is caused >> by my having categorized things like my 2015 tax payment as >> Expense:Tax:CZ:Income:2015. Not ideal in retrospect, I think. Still >> thinking it through. >> >> Regards, >> >> bex >> >> >> -- >> >> --- >> 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 ledger-cli+unsubscr...@googlegroups.com. >> 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 ledger-cli+unsubscr...@googlegroups.com. >> 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 ledger-cli+unsubscr...@googlegroups.com. >> 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 ledger-cli+unsubscr...@googlegroups.com. > 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 ledger-cli+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
