Grzegorz/Adam and all, I saw the Crowbar video and also a Crowbar presentation a few weeks ago (I believe it was on YouTube).
It caught my interest, and I did visit the Crowbar Wiki, and although I have two C6100's (with four nodes each), and I really do want to get started with CrowBar, because I liked what I saw with the YouTube video and the powerpoint presentation (that Rob did), I do agree that the User documentation definitely needs some work. If you need help with user documentation, then I would really like to help out with updating the Crowbar documentation. To be honest, I'm not all that concerned with how the website looks (at this point), and a Wikipage is just fine, just as long as the user documentation is extremely detailed, incredibly useful, easy to understand, and it's fairly easy to get started using Crowbar. Websites are nothing but cosmetic (in my opinion), and we really do need good Wiki documentation (for new users). Also having downloadable/printable (PDF/Microsoft Word) documentation manuals would be extremely nice as well. I visited here: https://github.com/crowbar/crowbar/wiki/User-documentation I was thinking about creating a "Quick Start Guide" (Installation Guide) and a detailed User's Guide and an even more detailed Configuration Guide (on how to install and configure individual modules/barclamps). 1) *Quick Start Installation Guide* - Will help the user get Crowbar setup and installed in under 10-15 minutes (from start to finish). 2) *User's Guide* - Will help the user become familiar with how Crowbar works, what the various menu items do, and how to deploy Crowbar (and add modules to Crowbar). 3) *Configuration Manual* - Will give in depth instructions on how to configure crowbar (and/or other modules/barclamps or third-party modules/software) with lots of screen shots and detailed step-by-step instructions on how to install, and configure each of these modules. 4) *Administrators Guide* - Will give instructions (for System Administrators) on how to remotely deploy Crowbar, how to monitor systems, how to add modules, how to read/monitor logs, etc. Also the one thing that I found extremely confusing was the term "barclamps". As a new user, it's an extremely confusing term. I think they should just be called "*Modules*". At least most new users understand what a "module" is. You can add in modules but the term "barclamps" makes no sense. I would vote to change all "barclamps" to "modules". I really think they should be called "Crowbar Modules" just so it's easy to understand from a new user's perspective. I was sifting through documentation, trying to figure out what a "barclamp" was (or what/why I even needed it or one) before I finally realized that "barclamps" were a term to describe add-on modules. Using the term "modules" is much more *user friendly*, and much *easier* to understand. KISS (Keep It Simple Stupid) is a term that most developers often forget when they are trying to develop software and they often try to "get creative" with naming things (which only adds more confusion to new users). Just keep it simple, and call a module a *module*. It's much easier for noobs (such as myself) and helps us understand (by using simple and easy to understand terms) but the term "barclamps" is way too confusing and really makes no sense at all. I was honestly thinking of creating a "fork" project, just to try and make this a bit easier to understand (but with all of the Crowbar 2.0 refactoring going on, it might make sense to just hold off and wait till Crowbar 2.0 is completely finished). This definitely needs quite a bit of work in terms of user documentation, and "user friendly" documentation. I'm extremely busy over the next few weeks, but I'd be willing to help with updating the wiki pages (to make them clearer and easier to understand). I'll probably ask a bunch of questions over the next few weeks (just so I understand) and then I'll try to help update documentation as I go, so hopefully we can improve the documentation quite a bit over the next few weeks. I'll even try to start a few Microsoft Word document(s) and create a new User Manual (in Microsoft Word) with a table of contents, and detailed step-by-step instructions, and then later I can print it as a PDF that we can post to the WIKI and also include with the Crowbar distro. That way users will have a PRINTABLE (and downloadable) manuals that they can use. That way new users can just read the "Installation Guide" and "Quick-Start Guide" and "User Manual" and "Administrator's Manual". It might take some time to get all of this done, but hopefully I can help with the documentation and we can get something written up (and get the documentation completed) before the 2.0 refactoring is completed. Is Crowbar 2.0 even functional at this point? I've spent three days just skimming stuff over, and I'm ready to dive in, but I would like to focus on installing Crowbar 2.0. I'm just not quite sure on the status of Crowbar 2.0 at this point, and if I start working on documentation I would probably want to start working on documentation for the latest/upcoming Crowbar 2.0 release. *> As you said, it will stay for "a small bunch of hackers", I think.* At this point, yes. But once we can get the documentation improved, and make it look extremely good (and easy to use and easy to understand) then hopefully more people will begin to download the crowbar distro and begin to use it. A wiki page in my opinion is perfect for right now. A fancy website (in my opinion) is something that can come much much later. I would focus more on the documentation (designing a nice wiki documentation page) and creating nice Word documents (that we can put into a PDF format) that users can just download and get started with Crowbar fairly quickly. If anyone else wants to help with documentation updates, please let me know. Also if it's ok, I would like to have "edit" access to the Crowbar wiki pages, so that I can at least start to add/edit pages and work on the user documentation as I go. I'm a complete NOOB with Crowbar right now, so this is the absolute BEST TIME for me to help start working on updating new user documentation. Anything that I don't understand, I can easily pester the developers for answers and then help explain (in great detail) in the user documentation and in the Wiki pages. That way new users can at least understand what Crowbar is, how it works, and how to get started (easily and quickly). Also do we have a detailed "*road map*" for the project? (A projected timeline as to when the refactoring will be done, when 2.0 will be officially released, or when/what particular "modules" or "barclamps" will get started/finished, and what each of these "modules" does?) Also please post a "release schedule" as part of the road map. (So we can at least understand when Crowbar 2.0 alpha or 2.0 beta, or Crowbar 2.0.1 will be released and a long detailed list of everything that needs to be worked on and included before/with each release). So that way we can at least understand (and new/future users understand) when the new releases will be coming, and also it helps me with working on documentation because at least I understand the timeline and what new features/modules are going to be added so that these can be included with the new/updated documentation (that will be done/ready when the new software release is ready). Something similar to this here: https://wiki.ubuntu.com/Releases Having some form of project "release" schedule (for Release Candidates, etc.) would be helpful so at least we can get documentation done, and know what features/modules will be included with each packaged release/distro. Does anyone have any idea as to when Crowbar 2.0 will be finished/released? Does 2.0 even work at this point? I'm still extremely new to the project, and I'm probably going to be sifting through all of the existing documentation during this next week or two, and then hopefully I can dive in to help with updating, editing, and I'll probably bombard you with quite a few questions/problems that I face while installing, and hopefully we can get all of the documentation improved over the next couple of weeks. I would like to start working on improving the Wiki pages, and begin working on hard-copy (Microsoft Word / PDF) documentation over the next couple of weeks, and hopefully I can have nice detailed manuals written before Crowbar 2.0 or 2.0.1 is released (after all of the crowbar refactoring is completed). *> 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). * Yes, I completely agree. I'm willing to step forward and help out with user documentation. Mark On Fri, Mar 15, 2013 at 9:47 PM, Grzegorz Witkowski <[email protected]>wrote: > Hi Adam and all, > > Great point. > I asked about the documentation a while back and any pointers how to start > the journey with Crowbar if I remember. I received a reply and checked the > site. > What happened? The Crowbar github and wiki really scared me. Totally user > unfriendly in my opinion. They look like my pages when I was learning > basics of HTML over 13 years ago. They might be easy for someone who uses > them on a daily basis, but for a someone new, not at all. For those > reasons, I did not come back to Crowbar really. > I saw that Juju site and after just watching the video on a main page I > wanted to play with it and start installation. That says everything. > Crowbar project definitely needs a proper eye-catching website and real > documentation in different formats. Without them you can forget about > getting this project anywhere these days. As you said, it will stay for "a > small bunch of hackers", I think. > People have no time to dig such sites. They need fast, compact and easy > information. I read years ago, that if someone does not find interesting > thing or what they are looking for on a website within 7 seconds, will > leave the site and won't come back. > > Kindest regards, > Grzegorz > > P.S. > Sorry, but the Crowbar mascot (the purple rabbit) is terrible in my > opinion. > > > > On Fri, Mar 15, 2013 at 1:17 PM, Adam Spiers <[email protected]> wrote: > >> 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/ >> > > > _______________________________________________ > Crowbar mailing list > [email protected] > https://lists.us.dell.com/mailman/listinfo/crowbar > For more information: http://crowbar.github.com/ >
_______________________________________________ Crowbar mailing list [email protected] https://lists.us.dell.com/mailman/listinfo/crowbar For more information: http://crowbar.github.com/
