The “community should self govern” thing seems dead in the water no matter how we do this imho, as I suspect the threshold is that people simply lack the desire / courage / empowerment to edit the docs as they are. The advantages would be the same as always, and I still don’t see a nightmare scenario with the issues (because there really aren’t that many opened on the docs repo). If we don’t do something more drastic I still think moving them into the main repo is a good thing to do. I would still like to do something better with the docs. I’m not necessarily convinced that’s the case any more, but those are the problem statements. I was thinking GitBook might solve both these things in one change. A WYSIWYG editor probably wouldn’t hurt but I don’t think it’s essential either. I suspect a more Wiki-like approach here would help. Currently the README talks about a weird compilation process and tools and the docs are in an odd format (that I’ve personally grown to dislike, too). There are probably lots of reasons for this and I can’t know them all, but the docs being tricky to get your head around as a newbie can’t help the situation. The second is that we don’t get a lot of “external” contributions, in my opinion. If I could expect API changes to also change the relevant docs in the same PR, and then later do a git diff v1.0.0.v1.5.0 - docs/rest/ that would be hugely helpful to me. As is, there is no good way to tie docs to a given release version and no good way to make code + docs changes (so we forget the latter). The first is that I want to integrate the docs with the code more. There’re two entirely different problems I want to solve.
0 Comments
Leave a Reply. |