Judd Maltin ([email protected]) wrote: > Thanks for putting an eye to this, guys. > > The top of the page, with my h1 and h2, are my new additions. The bolds > are Robs originals towards the bottom.
Ah, I see. > Deeper curation is definitely required. This was a first pass at enriching > and updating. I wish the github wiki would allow html embedding. It does allow embedding of some HTML - <table> at least ... > Youtube has nice rich tagging, etc. Plus, there no TOC features, except the > sidebar plugin. The lack of ToC is tracked here: https://github.com/gollum/gollum/issues/380 and it looks like someone might implement it soon due to a sudden burst of energy: https://github.com/gollum/gollum/issues/648 However there are other solutions, e.g. this looks pretty nice: https://github.com/hybridgroup/GitHub-Wikifier > I think it would take a few hours to get it just right. Maybe, but it would only take 20 mins to make some vast improvements. "If a thing is worth doing, it is worth doing badly." ;-) > Time I'm not assigned. I understand that right now we're all feeling the heat at the moment due to the aggressive release schedule - and please take the following remarks as general observations on the project rather than any kind of comment on your own great work! - but I believe it's a false economy to deprioritise documentation tasks even when under pressure to accomplish other goals. As well as the immediate benefits which good documentation brings to existing contributors (where the break-even point always happens earlier than I expect), there is a potentially huge but currently untapped community out there who could help us move a *lot* faster. But one of the big reasons that Crowbar has not seen widespread community adoption yet is that we still don't have friendly documentation (although we got a *lot* closer in the last few months). Look at: http://crowbar.github.com/ and now compare it with: https://juju.ubuntu.com/ The difference is *so* enormous that if someone is looking for a solution in this space, currently they are almost guaranteed to pick Juju regardless of any technical considerations, simply because the Juju website portrays Juju as an incredibly active, healthy, credible, friendly project with significant momentum, with backing from a strong community. In contrast, our website is more like what you'd expect to see from a project run by a small bunch of hackers in their spare time, and I wouldn't expect most newcomers to delve deeply enough to realise that's far from the reality. In November I submitted a Trello card to address the public website: https://trello.com/c/dBW9dlVu but despite it being on the current sprint board ever since, AFAICS there's been zero progress so far. Didn't we have someone assigned to work on this? So in summary, I believe we are vastly under-estimating the importance of having a decent documentation, or at least under-prioritising it. Sorry for the rant, but I think we really need to address this now if we want "market" Crowbar and attract new contributors at imminent events such as the Havana summit. If you made it this far, thanks for listening, and sorry for raising an uncomfortable issue ;-) _______________________________________________ Crowbar mailing list [email protected] https://lists.us.dell.com/mailman/listinfo/crowbar For more information: http://crowbar.github.com/
