Tango Almanac

pragma Joined: 05/28/04 Posts: 52

Posted: 06/19/07 17:11:42 Modified: 06/19/07 17:12:58 Once upon a time, I had a copy of this: http://www.amazon.com/Java-Developers-Almanac-1-4-Reference/dp/0201752808 It saved me endless hours of scouring through message forums and endless pages of javadoc, just to find some obscure piece of functionality that nobody else ever used. Anyway, the lack of a functional directory or almanac for Tango has caused me some headache since half this stuff was in Mango. As much as we do our best to organize code into a good tree of widgets, the namespaces only do so much to convey what operations are encompassed within. Even a site-wide search will only reveal method names and tutorials, which isn't enough when you're looking for how to properly compose objects together for various tasks. For example, Tango's IO model allows for some very inventive object compositions that are not at all obvious to the first-time user. Doubly so for people that are used to working with stream-oriented IO. While these things could be placed in the API documentation, you could easily quadruple the size of those pages covering all the possibilities - and that's probably a bad things since it abuses the intent and scope of the document. FWIW, even Phobos' documentation has this weakness. Folks are always asking in D.learn how do to things that aren't always obvious from the docs. Another take on this is what the ColdFusion? and PHP online doc pages have become. The various comments sections are probably more useful than the formal docs themselves, becuase they're rife with so many use-cases and practical examples. While we're looking to foster that kind of invovlment here, I think we can do even better. So what I think is needed is a Tango Almanac section of the wiki that lists, by task, various things that people are going to want to know how to do. Any given task description wouldn't have to include much; just a code snippet and two lines outlining what the snippet does (to facilitate searching). This way, it doesn't become the drudge that writing a formal tutorial section usually entails. I know this looks like a massive undertaking if looked at on the whole. Instead, I think this where the power of a wiki can really shine for Tango. We need to set up a few starter entries, and encourage people to post their own experience. Additional entries can also be harvested from the forums and comments sections as time goes on. -- EricAnderton at yahoo

Author	Message
larsivi Joined: 03/27/04 Posts: 614	Posted: 06/19/07 19:23:49 You are not the first to propose such a thing, it's obvious that a quick reference/FAQ/nugget collection sort of thing would be very handy. If you look in trunk/doc/quickref.pdf you see a start on something like this (a printable document). But I agree that we really should have something on the wiki that indexes/collects every little nugget there is in some fashion. For instance can you already find many nuggets and typically FAQ answers in the forums. If you have an idea on how it could be structured on the wiki, couldn't you put it forth? All the API docs have links into the wiki, so if we set up the structure, maybe more of the users would be willing to add comments there that would be placed correctly into the almanac. Brad had some really interesting ideas on how the docs could be built up such that by tagging the material, you could filter it by adding and removing tags to your search criteria in a fairly dynamic fashion, but I suspect that would need something that Trac currently is not.
pragma Joined: 05/28/04 Posts: 52	Posted: 06/19/07 21:13:41 larsivi wrote: If you have an idea on how it could be structured on the wiki, couldn't you put it forth? All the API docs have links into the wiki, so if we set up the structure, maybe more of the users would be willing to add comments there that would be placed correctly into the almanac. The only think keeping me from spearheading this right this second is that there's no "Test Tango web", so I'd be modifying the production wiki directly. Provided I have the team's blessing, I can go ahead and put up a starter page under "wiki/Almanac". larsivi wrote: Brad had some really interesting ideas on how the docs could be built up such that by tagging the material, you could filter it by adding and removing tags to your search criteria in a fairly dynamic fashion, but I suspect that would need something that Trac currently is not. Yea, Brad is going to pretty much re-write Trac by the time he's done with it. He went on for a while last night explaining to me all the ideas he's had. I've seen some trac-hacks that allow for metadata tagging of wiki nodes (I think) - it's not a new idea, but something that the Trac wiki could probably use. Then again, there's nothing keeping us from dumping "tags" directly into the footer of any wiki page so they can be picked up by full-text searches. -- EricAnderton at yahoo
larsivi Joined: 03/27/04 Posts: 614	Posted: 06/19/07 22:12:33 pragma wrote: Provided I have the team's blessing, I can go ahead and put up a starter page under "wiki/Almanac". Go ahead :) I could always delete if you mess up ;)
pragma Joined: 05/28/04 Posts: 52	Posted: 06/20/07 16:27:21 -- Modified: 06/20/07 16:29:07 by pragma Okay, a *very* lightweight example is online now: Almanac/tango.io.FilePath The good 'ol Java Almanac is much more heavily cross-referenced, but I don't see a practical way of doing this in a Wiki without some serious macro support or maintaining the thing offline in some fashion. I think we can proceed with the pattern I've put online for now, and rely on searching to close the gaps until something better comes along. More examples from the Java community: http://www.exampledepot.com/egs/ http://java.sun.com/developer/codesamples/examplets/index.html One more thing: is anyone else pining for breadcrumb support in the wiki? It's tough to navigate in there when you have a tree that's more than 3 levels deep, and you must explicitly code in back-links everywhere if that's what you need. -- EricAnderton at yahoo
larsivi Joined: 03/27/04 Posts: 614	Posted: 06/20/07 16:43:40 pragma wrote: Okay, a *very* lightweight example is online now: Almanac/tango.io.FilePath Hmm, have you looked at tango.io.FileScan? and the examples in svn? pragma wrote: One more thing: is anyone else pining for breadcrumb support in the wiki? It's tough to navigate in there when you have a tree that's more than 3 levels deep, and you must explicitly code in back-links everywhere if that's what you need. We talked about back-links and such last year, but ended up with not putting them in explicitly (partially because they melt too much into the normal page look, partially because it would be nice to have some more automatic possibilities. Oh, and what would breadcrumb support be (unknown phrase to me)?
pragma Joined: 05/28/04 Posts: 52	Posted: 06/20/07 21:44:08 larsivi wrote: Hmm, have you looked at tango.io.FileScan? and the examples in svn? I have. That technique for a recursive file listing is a little nugget I've had lying around since I was using Mango. It has different properties than what filescan can offer, and vice-versa. Perhaps I should document that in the Almanac entry, and supplement it with an entry for the FileScan? sample. As for the examples, I just finished browsing them. Do you think there's room for both approaches here, or should one be abandonded for the other (Wiki vs SVN)? larsivi wrote: We talked about back-links and such last year, but ended up with not putting them in explicitly (partially because they melt too much into the normal page look, partially because it would be nice to have some more automatic possibilities. Sounds like a good reason to make it a macro then. larsivi wrote: Oh, and what would breadcrumb support be (unknown phrase to me)? The "breadcrumb trail" (usually just called a "breadcrumb" in web-speak) gets its name from the Fairy Tale "Hansel and Gretel". It shows you where you are, and where you were. Breadcrumb trails and backlinks are close to the same thing, but breadcrumbs give you all the links back to root. The Forum links ("Forum Index » Tango Wish List » Tango Almanac") above are an example of a breadcrumb. -- EricAnderton at yahoo
larsivi Joined: 03/27/04 Posts: 614	Posted: 06/22/07 19:19:13 pragma wrote: larsivi wrote: Hmm, have you looked at tango.io.FileScan? and the examples in svn? I have. That technique for a recursive file listing is a little nugget I've had lying around since I was using Mango. It has different properties than what filescan can offer, and vice-versa. Perhaps I should document that in the Almanac entry, and supplement it with an entry for the FileScan? sample. As for the examples, I just finished browsing them. Do you think there's room for both approaches here, or should one be abandonded for the other (Wiki vs SVN)? It is very good with a sizable number (meaning more than we have now) of examples in SVN, for several reasons; They're very easy to get going with when you check out or download Tango. They are in themselves tests on several functional aspects of Tango, that don't necessarily work well in built in unittests (but perhaps should be put in a more rigorous testing framework (different topic altogether of course)). They tend to root out some compile time errors that you won't find when just compiling the library, in particular those related to linking. It is also very good to have examples in the Wiki, because they there are closer to the rest of the online documentation, they will pop up in searches on particular keywords (this is probably where the Almanac will shine when it fills up, the Trac search is really useful, but is probably mostly forgotten when looking for information), and in the wiki they can more easily have their documentation extended if needed, and annotated (annotations will work much better for code viewable on the same page as compared to in a code editor). So for the specific question above related to file listing, both should be mentioned :) pragma wrote: larsivi wrote: We talked about back-links and such last year, but ended up with not putting them in explicitly (partially because they melt too much into the normal page look, partially because it would be nice to have some more automatic possibilities. Sounds like a good reason to make it a macro then. Probably, although one will still have the problem with mantainance of the macro content (depending on exactly which parameters one can set). Probably a different topic altogether too, btw :)
kris Joined: 03/27/04 Posts: 581	Posted: 06/27/07 06:14:43 the almanac could also be hooked up via the API docs. For example, clicking on the FilePath? link associated with the text "class FilePath?" could take one to the associated almanac entry?