[prev in list] [next in list] [prev in thread] [next in thread]
List: helix-open-discuss
Subject: [Open-discuss] Re: devdocs directory
From: Rishi Mathew <rmathew () real ! com>
Date: 2005-07-16 19:39:08
Message-ID: 6.2.1.2.2.20050716123124.06c812e8 () mailone ! real ! com
[Download RAW message or body]
This is a MIME-formatted message. If you see this text it means that your
E-mail software does not support MIME-formatted messages.
David,
(cc'ing open-discuss)
Thanks for your comments. See inline..
At 01:45 PM 7/13/2005, David Hirayama wrote:
>Rishi,
>As a total newcomer to the Linux scene, I can't really weigh in on your
>proposed process per se. I'm simply not familiar enough yet with the Helix
>environment to do so. As such, my comments (for now) mostly pertain to
>readability and presentation. Pending your reply, I think I'll be able to
>comment on the process itself.
>
>As a general comment, I found I had to study your doc to grok it. It
>shouldn't have to be so hard. If you're amenable to my comments, other
>future newbies will have an easier time digesting it.
>-----------------------------------------------------------------------------
>1) Is the scope of your doc just FRD and SODs?
>The title is inconsistent with the range you specify for the TTT field
>(which includes MRD and USR).
Based on your suggestion, the scope now includes Test Plans as well.
It is a 3-char field and it does NOT have to be an absolute acronym(which
takes the 1st letter of the 1st 3 words)
>2) Can you provide some examples, especially with regard to locating
>documents?
>You provide verbal descriptions. Much easier to understand would be
>explicit examples for the location of each doc type. And even better would
>be examples that tie in with a specific project (so that I, as the reader,
>can browse through CVS to trace out what you're saying and see actual docs).
I think we discussed this in the meeting, so document browsing can be done
through other ways rather than CVS-browsing
>3) Can you provide an exec overview of the whole process?
>It'd be very helpful if you list the basic steps (w/o their details) in
>the Intro. As is, this info is weaved into the detailed descriptive text.
>Something like the following would serve as a great visual reference while
>navigating through the denser detailed info:
> 1 - Sign the Contributor Agreement
> 2 - Name your document
> 3 - Write your document
> 4 - Find its proper location
> 5 - Notify the community
> 6 - Incorporate community feedback
> 7 - Wait for final approval
> 8 - Begin development
Done.
>4) Do all feature specs go under \Common?
>In your step #5, I think you're saying there are only two types of docs:
>feature-level docs and product-level docs. Feature-level docs go in
>\Common. Product-level docs go in product level directories. Is this
>correct? If so, remove the verbage "if you want to change a feature"
>because it implies the case "if you want to change something else" and you
>don't speak to this latter case.
I am hoping to make a change so that we have all client-side docs in 1
location helix-client/www/[year]/devdocs, making it easily browseable
through the "Docs" tab of the project. Same for "player" "helix-server" and
"helix-producer"
>5) So how do the docs to which you refer in steps #5 and #6 differ??
>You mention feature-level and product-level docs in step #5. These docs go
>in \Common or \<product>.
>You mention "public documentation" in step #6. These docs go in
>/cvsroot/<project>/www/<year>/devdocs.
>What's the difference between these two doc classes? What's the rationale
>for putting them in different places? Can you convey this info to the reader?
See above.
>6) What about test plan submission?
>Is this covered somewhere else? If not, why not expand the scope of your
>proposed doc to cover them? Might as well since it's an incremental effort
>to do so now rather than going through this process again for test plans
>at some future time.
Done.
Thanks,
Rishi.
>-----------------------------------------------------------------------------
><prior thread deleted>
Rishi Mathew
Software Development Engineer
Helix Community
RealNetworks, Inc.
rmathew@real.com
http://www.helixcommunity.org
http://www.realnetworks.com/products/support/devsupport.html
[Attachment #3 (text/html)]
<html>
<body>
David,<br><br>
(cc'ing open-discuss)<br>
Thanks for your comments. See inline..<br><br>
At 01:45 PM 7/13/2005, David Hirayama wrote:<br>
<blockquote type=cite class=cite cite="">Rishi,<br>
As a total newcomer to the Linux scene, I can't really weigh in on your
proposed process per se. I'm simply not familiar enough yet with the
Helix environment to do so. As such, my comments (for now) mostly pertain
to readability and presentation. Pending your reply, I think I'll be able
to comment on the process itself.<br><br>
As a general comment, I found I had to study your doc to grok it. It
shouldn't have to be so hard. If you're amenable to my comments, other
future newbies will have an easier time digesting it.<br>
-----------------------------------------------------------------------------<br>
1) Is the scope of your doc just FRD and SODs?<br>
The title is inconsistent with the range you specify for the TTT field
(which includes MRD and USR).</blockquote><br>
Based on your suggestion, the scope now includes Test Plans as well.<br>
It is a 3-char field and it does NOT have to be an absolute acronym(which
takes the 1st letter of the 1st 3 words)<br><br>
<br>
<blockquote type=cite class=cite cite="">2) Can you provide some
examples, especially with regard to locating documents?<br>
You provide verbal descriptions. Much easier to understand would be
explicit examples for the location of each doc type. And even better
would be examples that tie in with a specific project (so that I, as the
reader, can browse through CVS to trace out what you're saying and see
actual docs).</blockquote><br>
I think we discussed this in the meeting, so document browsing can be
done through other ways rather than CVS-browsing<br><br>
<br>
<blockquote type=cite class=cite cite="">3) Can you provide an exec
overview of the whole process?<br>
It'd be very helpful if you list the basic steps (w/o their details) in
the Intro. As is, this info is weaved into the detailed descriptive text.
Something like the following would serve as a great visual reference
while navigating through the denser detailed info:<br>
1 - Sign the Contributor Agreement<br>
2 - Name your document<br>
3 - Write your document<br>
4 - Find its proper location<br>
5 - Notify the community<br>
6 - Incorporate community feedback<br>
7 - Wait for final approval<br>
8 - Begin development</blockquote><br>
Done.<br><br>
<br>
<blockquote type=cite class=cite cite="">4) Do all feature specs go under
\Common?<br>
In your step #5, I think you're saying there are only two types of docs:
feature-level docs and product-level docs. Feature-level docs go in
\Common. Product-level docs go in product level directories. Is this
correct? If so, remove the verbage "if you want to change a
feature" because it implies the case "if you want to change
something else" and you don't speak to this latter
case.</blockquote><br>
I am hoping to make a change so that we have all client-side docs in 1
location helix-client/www/[year]/devdocs, making it easily browseable
through the "Docs" tab of the project. Same for
"player" "helix-server" and
"helix-producer"<br><br>
<br>
<blockquote type=cite class=cite cite="">5) So how do the docs to which
you refer in steps #5 and #6 differ??<br>
You mention feature-level and product-level docs in step #5. These docs
go in \Common or \<product>.<br>
You mention "public documentation" in step #6. These docs go in
/cvsroot/<project>/www/<year>/devdocs.<br>
What's the difference between these two doc classes? What's the rationale
for putting them in different places? Can you convey this info to the
reader?</blockquote><br>
See above.<br><br>
<br>
<blockquote type=cite class=cite cite="">6) What about test plan
submission?<br>
Is this covered somewhere else? If not, why not expand the scope of your
proposed doc to cover them? Might as well since it's an incremental
effort to do so now rather than going through this process again for test
plans at some future time.</blockquote><br>
Done.<br><br>
Thanks,<br>
Rishi.<br><br>
<blockquote type=cite class=cite cite="">
-----------------------------------------------------------------------------<br>
<i><prior thread deleted></i> </blockquote>
<x-sigsep><p></x-sigsep>
<br>
<font size=2><b>Rishi Mathew<br>
</b>Software Development Engineer<br>
Helix Community<br>
</font><font size=2 color="#0000FF"><b>Real</b></font><font size=2>
Networks, Inc. <br>
rmathew@real.com <br>
</font><font size=2 color="#0000FF"><u>
<a href="http://www.helixcommunity.org/" eudora="autourl">
http://www.helixcommunity.org<br>
</a>
<a href="http://www.realnetworks.com/products/support/devsupport.html" eudora="autourl">
http://www.realnetworks.com/products/support/devsupport.html<br>
</a></font></u></body>
</html>
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic