On Sun, Sep 13, 2009 at 12:31 AM, Barry Warsaw <[email protected]> wrote: > On Sep 12, 2009, at 12:24 AM, Karl Fogel wrote: ... >> I think we should try to structure the wiki essentially as a reference >> document, with a few narrative paths leading from the front page or from >> other prominent locations. A "Tricks and Tips" page looks good at >> first, but as it grows it raises two questions: >> >> 1) When a reader shows up trying to learn about X, what would make >> them go to the "Tips and Tricks" page? >> >> 2) When a reader shows up trying to get an overview of how to hack on >> Launchpad, what would make them turn to the "Tips and Tricks" page? > > Maybe it should be called Launchpad Cheat Codes? :) > > You might call this Appendix material. It's interesting and useful but not > essential to your LP hacking experience. I appreciate the goal oriented > organization though I'm not sure how you'd place this page into that > structure. > > As an aside, I think that structure is fine for new people, but it's not as > useful (and perhaps detrimental) to experienced developers. It's like the > difference between a tutorial and a reference manual. When I know what page > I'm looking for, I really don't want to be distracted by having to work the > path backward to remember where to start my hunt. > >> The answer to both is "nothing at all". In other words, instead of a >> generic Tips and Tricks page, we should just find the proper location >> for *each* tip and trick as we add it. In this case, it was high time >> we started a Debugging page, and if people see other material in the >> wiki that belongs there, please move it there (leaving cross-links as >> appropriate). > > Maybe. This of course is an age old dilemma. Do you split the information > up and place it near where you think it's going to be useful, or to you cram > it all together into one page where at least you can easily remember where > that tip is. The answer of course is "yes and no" to both questions (IOW, > you can't win :). I guess that's what searching is supposed to solve. >
"Tips and Tricks" pages, like FAQ pages, are optimized for writers, not readers. If my tests are slow and I want to know how to make them faster, I'll look for a page like that, not a tips page. If I want to know how to do date formatting or am looking for better tools for doing code reviews, I'll search for pages like that, rather than "FAQ" or "Tips". > In any event, I've laid out my original intent and some concerns I have. > I'm happy to defer to consensus, or even the "he who does the work, > decides" ethic. :) > I'm always happy to defer to that latter ethic :) >> I'll ask about the reST format thing in another mail, as it's really a >> separate topic. >> >> Thanks again. My page rename notwithstanding, this is a really good >> tip! > > Sure thing! My call to arms still stands. We've all got these little > tricks in our heads, buried in email threads, shell histories, and muscle > memories. Let's get them into the wiki! > I fully support this call to arms.[1] However I'm sure that for many of these cases, we could do better by: - writing a script that just does it. - fixing the error message to be more readable - adding a convenience API etc. jml [1] As long as by "wiki", you don't mean https://dev.launchpad.net/Hacking. ;-) _______________________________________________ Mailing list: https://launchpad.net/~launchpad-dev Post to : [email protected] Unsubscribe : https://launchpad.net/~launchpad-dev More help : https://help.launchpad.net/ListHelp
