Write documentation
martinandersson opened this issue · comments
Hey I have to be honest. For being a tool to generate documentation, your own documentation is like the worst. Take the new website, for example, it doesn't even say wtf gitbook is. And there are zero pointers to any useful docs on the topic. The "getting started" guide simply asks me to sign up for an account of some sort (yaaaay, another account)!
In particular, after having spent a few days on google it is very confusing to try to decipher if "gitbook" is a command I can use locally or if you're moving to some kind of Github-integrated service fully online. Or to put it differently, even if I did know all about the github-cli, should I abandon this product for something more "platform independent" that doesn't require me to sign up somewhere and restrict me to a slow and buggy browser?
Had I not had a work colleague to give me the gist, I could literally not be able to figure out why I should use your tool and what it does. But he did, and he showed me there's a gitbook command with options build and serve. But how these very core fundamentals work is something not even your "legacy" documentation has anything to say about. For example, I ran the serve command and all of a sudden my GIT repository picks up a whole bunch of random weird-ass files in a subdirectory "_book". Of course I can grok this is a secretive output folder that the gitbook command created. But where is it documented? Nowhere according to my search.
Look guys, please lead by example lol.