cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Tony Collen <>
Subject Re: [WIKI-UPDATE] Tutorials Snippets HowTos Thu Apr 3 20:00:07 2003
Date Fri, 04 Apr 2003 15:27:16 GMT
On Fri, 4 Apr 2003, Diana Shannon wrote:

> On Thursday, April 3, 2003, at 01:11  PM, Tony Collen wrote:
> > I'm trying to remove the overlap between the notion of a Tutorial and
> > How-To.
> Do you mean reinforce the distinctions between a How-To and a Tutorial?
> I agree with what you did.

Nope, in fact, ideally, I think we should get rid of one of the terms and
choose the other.  The choice to make Tutorials all of the off-site links
was mostly arbitrary.  The only relation I saw on the Tutorials page was
that all of the links except 2 were off-site, and the 2 on-site links were
described as "How to $whatever".  It just seemed natural.

So perhaps we need to rename Tutorials to something like "Other sites with
Cocoon help", and keep the notion of a "How-To" on the wiki.  IMO
Tutorials are just How-To docs, and possibly vice versa.

> > Any big objections to moving the content on [Snippets] to [FAQs] ?  We
> > could lose the [Snippets] page altogether and get rid of some cruft.
> I have no objections. It was created as a separate category originally
> with the idea that snippets would be displayed in a textarea box, where
> they could be readily copied. This is no longer necessary, now that we
> have wiki where such copies are simply a matter of clicking "Edit this
> Page".

Textarea?  Isn't copying off the web page easy enough? :)  With regards to
turning the snippets into FAQs, it would be simple enough to rewrite "Make
An Internal Pipeline" into "How do I make an internal pipeline?"
Although, I'm not sure as to how Frequently these Questions are asked, but
whatever =]

> However, what do you mean by the term "cruft". Let's be careful here.
> Even though we are using this for our documentation system, some people
> inevitable will have the wiki perception that major edits are rude. So,
> let's be thoughtful about removing cruft. Do you mean you are removing
> links from the index to certain pages you consider cruft?

I only meant cruft as in extraneous pages that we'd have to remove other
links to, like the Snippets page being referred to by BestPractices,
About, LeftMenu, and HowTos.  If we move the content to FAQs, we'll
probably want to clean up the links to the Snippets page on these other
pages.  Simple site maintenance.

> Definitely better if your language is alphabetized like English ;-).
> Still, I think the term "Basic" is too broad, now that we have so many
> How-Tos. I promise to take a stab at it over the weekend.

Well yeah, but the whole Wiki is Auf Englisch =]

Random thought:

What happens when we want to translate our docs?

Yeah, I know we're nowhere near requiring that yet.

Ever working for better docs,

Tony Collen
ICQ: 12410567
Cocoon: Internet Glue (A Cocoon Weblog)

View raw message