launchpad-dev team mailing list archive

[Barry Warsaw <barry@xxxxxxxxxxxxx>]

On Sep 12, 2009, at 12:24 AM, Karl Fogel wrote:

> Barry Warsaw <barry@xxxxxxxxxxxxx> writes:
> > I've also started a new page on the wiki for helpful Launchpad  
> > hacking
> > tips.  I'm tired, so I hope I haven't duplicated a page that lives
> > elsewhere already.  In any case, here it is:
> >
> > https://dev.launchpad.net/Launchpad%20Tricks%20and%20Tips
>
> This is excellent, thank you!
>
> I moved it to https://dev.launchpad.net/Debugging.  No criticism
> intended by the move -- "Wiki maintenance is hard, let's go shopping."

None take.  The essential nature of wikis is that they always need  
gardening. :)

However, "Debugging" isn't really what I had in mind for the page,  
even though it might seem like that based on the first/only entry on  
the page.  For example, the next thing I intend to write up (once I  
dig up those instructions) is how to run Launchpad with PostgreSQL on  
a ramdisk.  That's a "trick/tip/tidbit" but not a debugging aid.

So I really see this page as a collection of many of the little things  
we've discovered that makes Life With Launchpad easier, but which  
aren't essential to hacking on it, and may not even be of interest or  
appropriate for everyone on every platform.

Can we come up with a better name than "Debugging" given that intent?

> 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.

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'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!

-Barry

Attachment: PGP.sig
Description: This is a digitally signed message part