Documentation Observation redux, and suggestions
paul
ylluminate made at
https://groups.google.com/group/hobodev/browse_thread/thread/357ea2325151a224?hl=en
I agree with most of the issues he's raising. The documentation and
overall organisation of Hobo would really benefit from an overhaul. At
the moment the spread of info over website, ebook, cookbook (now 1.0
and 1.3 versions), googlegroups, lighthouse and github make it pretty
difficult for people to find information effectively.
I used to think it was just me (not being a full-time dev), but
recently I persuaded an ace guy with solid RoR experience to use Hobo.
Now he's got exactly the same love/hate relationship with Hobo that I
have. Productivity is fantastic until suddenly you hit a brick wall -
the magic stops working and hours (maybe days) of headscratching
ensue.
I have some suggestions:
- let's scrap the cookbook. i know it's a Hobo app, but wouldn't the
content be better in a wiki, easily editable by the community?
- scrap the ebooks too - this information should be in the same place
as the cookbook content.
- let's organise the website & documentation so that all of the
documentation is under one umbrella, with one look and feel.
- let's identify the areas that are not clear, and update with simple
examples.
- and finally let's get folks using the #hobo irc channel. I know irc
sucks in many ways, but it *does* improve ongoing communication and
would provide a place for folks to get directions. rdale and I have
been lurking there for a while, but most of the conversation is
github!
I hope this doesn't sound too negative. Happy to help with the work
(and bribe rdale to help too)
br
Paul
Owen Dall
Paul
--
You received this message because you are subscribed to the Google Groups "Hobo Dev" group.
To post to this group, send email to hob...@googlegroups.com.
To unsubscribe from this group, send email to hobodev+u...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/hobodev?hl=en.
paul
we're using ikiwiki, happy with it.
All content is markdown, can be pushed via git, or edited directly on
the webpage. All changes stay in git, so if someone vandalises it's
trivial to revert
br
Paul
On Nov 25, 2:38 pm, Owen Dall <od...@barquin.com> wrote:
> Paul,
>
> Thanks much for you input. Can you point me to an open-source wiki site
> that you like the best?
>
> -Owen
>
>
>
>
>
>
>
>
>
> On Thu, Nov 24, 2011 at 7:52 PM, paul <stori...@gmail.com> wrote:
> > Sorry to top-post, but looks like I can't add to the original post
> > ylluminate made at
>
> >https://groups.google.com/group/hobodev/browse_thread/thread/357ea232...
Owen Dall
Bryan Larsen
> Sorry to top-post, but looks like I can't add to the original post
> ylluminate made at
>
> https://groups.google.com/group/hobodev/browse_thread/thread/357ea2325151a224?hl=en
>
> I agree with most of the issues he's raising. The documentation and
> overall organisation of Hobo would really benefit from an overhaul. At
> the moment the spread of info over website, ebook, cookbook (now 1.0
> and 1.3 versions), googlegroups, lighthouse and github make it pretty
> difficult for people to find information effectively.
Not that it makes our situation better, but I'd like to note that
we're doing better than the Rails documentation, where the primary
mode of documentation appears to be blog postings. The big
advantage that Rails has is that its documentation is duplicated all
over the place -- you might find what you need in the Guides, on a
blog posting, in somebody's book or on StackOverflow. We don't have
the manpower to effect that massive duplication of effort, so...
>
> I used to think it was just me (not being a full-time dev), but
> recently I persuaded an ace guy with solid RoR experience to use Hobo.
> Now he's got exactly the same love/hate relationship with Hobo that I
> have. Productivity is fantastic until suddenly you hit a brick wall -
> the magic stops working and hours (maybe days) of headscratching
> ensue.
Yes, it is unfortunate. IMO, the primary advantage of Hobo over it's
competitors like ActiveScaffold is that there is no brick wall: you
should always be able to do what you want without modifying Hobo
itself, and the amount of effort you have to put in to do it should
be relatively proportional to the how different what you want to do
from the way Hobo does it.
Even if Hobo made that easy it would still be difficult for some: by
necessity, to extend Hobo to do X, you might have to know how to do X
in Rails.
>
> I have some suggestions:
> - let's scrap the cookbook. i know it's a Hobo app, but wouldn't the
> content be better in a wiki, easily editable by the community?
Some of the documentation could be easily moved to a Wiki, but other
pieces would lose something if moved.
For example, all of the taglib documentation is in DRYMLDoc format in
a comment just before the definition of the tag. Moving that would
make it harder to update the documentation when the tag itself
changes, and would make it possible for the source associated with the
tag documentation to be wrong.
Also, much of the manual is in rubydoctest format, which means that
the examples are executed every time the Hobo unit tests are executed,
ensuring that the examples are complete and without error.
The agility gitorial is a complete program split logically into github
commits. It would very quickly lose its coherence on a Wiki.
But your comment had two parts. You said "easily editable by the
community". All of the content is editable, but it's not "easily
editable". It's all on github in one way or another. And github
makes it very easy to edit pieces of the cookbook or the Hobo project
or agility or anything else. For example, to edit the DRYML guide,
go to this page:
https://github.com/tablatom/hobocookbook/blob/rails3/manual/dryml-guide.markdown
and then click on "fork and edit this file". Github makes it as easy
as many Wiki's. The problem is getting to the above URL in the first
place. That we can help with. We should have an "edit this file"
link at the bottom of every page in the cookbook.
> - scrap the ebooks too - this information should be in the same place
> as the cookbook content.
The recently completed conversion to LyX should make an HTML export
much easier & cleaner, so we should go ahead and incorporate this into
the cookbook.
> - let's organise the website & documentation so that all of the
> documentation is under one umbrella, with one look and feel.
> - let's identify the areas that are not clear, and update with simple
> examples.
> - and finally let's get folks using the #hobo irc channel. I know irc
> sucks in many ways, but it *does* improve ongoing communication and
> would provide a place for folks to get directions. rdale and I have
> been lurking there for a while, but most of the conversation is
> github!
The same applies for the IRC channel: please ensure that anything
useful makes it either to the mailing list or the documentation! :)
>
> I hope this doesn't sound too negative. Happy to help with the work
> (and bribe rdale to help too)
> br
> Paul
>
>
>
kevinpfromnm
One additional possibility that I did not have time to pursue is that the lyx book can source other files. If we could make the documentation sections source from the existing github info we'd have a book/site that would remain consistent with the changing documentation.
What would really be most helpful though would be having all the relevant materials be in a location easily searchable. As is, with a third in the book, a third in the group and a third in the cookbook makes it hard even for veterans to find information. Only way this can happen that I can see is if we have a usable forum on the cookbook site + indexed search. Google search might be workable if it's all in one domain though.
Owen Dall
--
You received this message because you are subscribed to the Google Groups "Hobo Dev" group.
To view this discussion on the web visit https://groups.google.com/d/msg/hobodev/-/DAPa-GA3UvIJ.
To post to this group, send email to hob...@googlegroups.com.
To unsubscribe from this group, send email to hobodev+u...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/hobodev?hl=en.
Owen
http://www.instiki.org/show/HomePage
On Nov 25, 1:57 pm, Owen Dall <od...@barquin.com> wrote:
> Yes, we need to find the best way to
>
> 1. Pull all content together, with physically or logically
> 2. Have a basic taxonomy that we can use to offer "Faceted" search which
> uses both metadata and sophisticated text capabilities
> 3. We are doing something similar at NIFA using the Google Search Appliance
> (GSA), which costs $25,000 per year per 1M "documents". Chris Woody on our
> team did a bang up job on the ETL and metadata.
>
> http://screencast.com/t/RPyttykV
>
> 4. Sunspot => Solr => Lucene has moved forward quite a bit, and perhaps
> could support most of what GSA offers
> 5. We were hoping that the google group technology would be giving us some
> of the the power of the GSA. Not even close. Would it be better to go
> back to using our own Q & A that we could manage and harvest more easily?
>
> I agree with Kevin that the new LyX (LaTex processor) gives us the
> opportunity to link content dynamically, and allow developers to create a
> PDF at any time that is easily searchable.
>
> Managing a "Knowledge Space" effectively (as we at Barquin call it) is a
> MAJOR endeavor. See an old article by Ramon from 2005:
>
> http://searchbusinessanalytics.techtarget.com/news/2240025766/Busines...
>
> As with any endeavor, TIME and MONEY are the limitations.
>
> -Owen
>
paul
Could we do something like
- incorporate the look n feel and content from hobocentral.net into
the cookbook
- bring in the book content too
- reorganise the top-level menus and homepage to provide a clearer
picture of where stuff is, how to get started, how to get help etc
- extend it to include a forum...
- plan to migrate the community discussion from google groups to the
forum
- possibly even migrate the content from the groups? but maybe it's
cleaner not to..
then we'd have pretty much everything in one searchable Hobo app?
paul
> Not that it makes our situation better, but I'd like to note that
> we're doing better than the Rails documentation, where the primary
> mode of documentation appears to be blog postings. The big
> advantage that Rails has is that its documentation is duplicated all
> over the place -- you might find what you need in the Guides, on a
> blog posting, in somebody's book or on StackOverflow. We don't have
> the manpower to effect that massive duplication of effort, so...
Fair enough. I've only been using Rails through Hobo, not had much
exposure to the Rails docs.
> Yes, it is unfortunate. IMO, the primary advantage of Hobo over it's
> competitors like ActiveScaffold is that there is no brick wall: you
> should always be able to do what you want without modifying Hobo
> itself, and the amount of effort you have to put in to do it should
> be relatively proportional to the how different what you want to do
> from the way Hobo does it.
Agreed. If you keep to the path it's easier, but if you don't know
where the path is, you can quickly end up in the woods.
> Some of the documentation could be easily moved to a Wiki, but other
> pieces would lose something if moved.
Taking on board what you, Kevin and Owen have said, I think the wiki
idea won't fly.
> and then click on "fork and edit this file". Github makes it as easy
> as many Wiki's. The problem is getting to the above URL in the first
> place. That we can help with. We should have an "edit this file"
> link at the bottom of every page in the cookbook.
Excellent. Any reason why there are so many repos, though? Couldn't
everything (at least everything docs related) be rationalised into
one?
> The recently completed conversion to LyX should make an HTML export
> much easier & cleaner, so we should go ahead and incorporate this into
> the cookbook.
Sounds good to me
Bryan Larsen
> everything (at least everything docs related) be rationalised into
> one?
What do we merge? The manual & the cookbook are in the same
repository already. We have a separate repository for the gitorial,
and then another repository for Hobo itself as well as one for each of
the plugins. Every separate repository represents a distinct chunk
of working code.
>
>> The recently completed conversion to LyX should make an HTML export
>> much easier & cleaner, so we should go ahead and incorporate this into
>> the cookbook.
>
> Sounds good to me
>
It seems to me that this is the start of our TODO list.
- full site search. Kevin, I believe that you started on this at one
time, didn't you?
- fix comments. We've got a pull request for this feature from iox
- "edit this page" links on every page
- pull more of hobocentral.net into the cookbook. Home, About,
Gallery, Community are trivial
- HTMLize the books and put them into the cookbook
- put the blog into the cookbook as well. A full-fledged blog is a
lot of work, but we can use Disqus or similar to do the hard stuff,
like spam detection.
Now the hard part: volunteers to do this stuff.
I've asked Tom to fixup the branches so that "master" can become our
development branch again. Until then, the "rails3" branch is the
development branch and has an actual README:
https://github.com/tablatom/hobocookbook/tree/rails3
I'm working on the jQuery part of Hobo 1.4, so that's sucking every
last minute of my spare time out but hopefully I can get an -pre
version of that out in a week or so.
Bryan
Owen Dall
--
You received this message because you are subscribed to the Google Groups "Hobo Dev" group.
To post to this group, send email to hob...@googlegroups.com.
To unsubscribe from this group, send email to hobodev+u...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/hobodev?hl=en.
paul
up some documentation.
But I'm stuck at first base as usual... can't get hobocookbook to
install on my mac, because
ERROR: Error installing mysql:
ERROR: Failed to build gem native extension.
and later..
*** extconf.rb failed ***
Could not create Makefile due to some reason, probably lack of
necessary libraries and/or headers. Check the mkmf.log file for more
details. You may need configuration options.
There's no mkmf.log file on my machine at this point :(
is there a good reason for the cookbook to require mysql?
On Nov 26, 2:43 pm, Owen Dall <od...@barquin.com> wrote:
> Yes, Bryan, we need to get our requirements down and find a path to
> execution...
>
> I will try to focus on locating what we can reuse from current/past client
> projects.
>
> Kevin did a nice tutorial with Sunspot. Venka will actually be building a
> prototype of faceted search using Sunspot for one of our clients.
>
> -Owen
>
Bryan Larsen
developmentmode. Just comment out the mysql gem (or mark it for
production modeonly) and uncomment the sqlite line.