On Tue, 22 Aug 2006, Mat Schaffer wrote:
>
> I'm all for walkthrough-style stuff in this document. I'd like to see this
> turn into a "Getting Started" type document as time goes on with relevant
As long as we don't lose too much focus I'd agree, anything to make
this easier for contributers to do the right thing(s).
> links to things like learning CVS. But maybe we should be more equal
> opportunity and link to a page that contains a number of CVS resources (if
> there such a page) rather than just go straight to the Pragmatic Book. Either
Yes, completely agree, but that was the reference I thought people
might have difficulty with, so I brought it up merely as an "edge
case" :-)
> way, I'm with you on that sentiment. Thought I disagree with the placement of
> the paragraph. I'm thinking the final document should be structured something
Which paragraph -- the one talking about the goal of this document
itself?
> like:
>
> - Getting set up (tutorial style)
> -- getting CVS copy
> -- setting up stdlib doc and compiling docs
> - Style guidelines
> -- Where and how to write, indenting (bulleted lists)
> - Submission guidelines
> -- Where and how to post your changes (bulleted lists)
sounds good to me.
>
> Lots of example terminal sessions, links to extra info, etc. And probably a
> link near the top that skips to the guidelines sections for people who just
> need a quick reference, maybe a table of contents like thing.
>
> I didn't quite get what you were saying about internal docs. But I think I
> see now. I think it could be nice for rdoc to support some sort of special
> marking as internal documentation that would be hidden by default (similar to
> the show/hide source) thing. A place for notes on tricky implementation. If
> that's what you're getting at, I like it. But I'm not sure it's something we
Yes, that's my idea.
> need to spend energy on right away. For the time being, the show/hide source
No, not now, but if it is worth doing then those familiar with Rdoc
internals will bear it in mind as things progress.
> function is probably good enough for most people. And we don't want to
But it would be nice to have formatted output in due course.
> implement it in a way that would encourage internal documentation getting out
> of hand (usually a sign that refactoring is needed).
Yes, "prefer working code over documentation" is still a helpful
idea when docs are deemed useful. keywords: balance. :-)
> -Mat
>
>
Thank you,
Hugh
>
>
>
>
>
|
