launchpad-dev team mailing list archive

[Jonathan Lange <jml@xxxxxxxxxxxxx>]

On Sun, Sep 13, 2009 at 12:31 AM, Barry Warsaw <barry@xxxxxxxxxxxxx> 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. ;-)