Walter wrote:
> "J Anderson" <REMOVEanderson@badmama.com.au> wrote in message
> news:caqs55$2060$1@digitaldaemon.com...
> 
>>Walter wrote:
>>
>>
>>>Sounds like a fine idea to me. Set up the wiki pages, and I'll add the
>>>links. The documentation can certainly use improvement.
>>>
>>>
>>
>>Ok, you can find all the pages at:
>>http://www.prowiki.org/wiki4d/wiki.cgi?Digital_Mars_Comment
>>
>>However please use the direct links as nobody likes going though
>>multiple pages to get somewhere.
> 
> 
> Thanks. So far, I've done it with the first 3 pages and the faq.

Cool. This is a terrific concept. I think it'll come in really handy.

As I mentioned to Joel in another branch of this thread, I made some suggestions for the pages to blend into the rest of the wiki a little better (such as using subpages and a naming convention). He seemed receptive to the ideas (but lacking in time), so I created them on the wiki. The home page for these new pages is http://www.wikiservice.at/d/wiki.cgi?DocComments.

Obviously, it doesn't make any sense to have two sets of these pages, so I'll delete whichever set isn't linked to by your webpages (once the dust clears).

-- 
Justin (a/k/a jcc7)
http://jcc_7.tripod.com/d/

J C Calvarese wrote:

> J Anderson wrote:
>
>> Walter wrote:
>>
>>> Sounds like a fine idea to me. Set up the wiki pages, and I'll add the
>>> links. The documentation can certainly use improvement.
>>>  
>>>
>> Ok, you can find all the pages at:
>> http://www.prowiki.org/wiki4d/wiki.cgi?Digital_Mars_Comment
>>
>> However please use the direct links as nobody likes going though multiple pages to get somewhere.
>
>
> Joel and everyone,
>
> I have some suggestions.
>
> I'm not sure why you've added the new sections rather than adding to the existing DocumenationAmendments section (I think Helmut added it for this purpose). Instead of having two competing wiki sections
> (DocumentationAmendments and Digital_Mars_Comment) perhaps we should just have one. If DocumentationAmendments is too verbose, we can delete that and recreate it as DocComments or DocumentComments.
>
> Also, instead of having separate pages, we could have subpages:
> DocComments/Arrays
> DocComments/Phobos
>
> I think it'd be helpful if the wiki page corresponded with the HTML filename (the filenames are shorter and probably less likely to change):
>
> abi.html    -> DocComments/ABI     "Application Binary Interface"
> intro.html  -> DocComments/Intro   "Introduction"
> phobos.html -> DocComments/Phobos  "Phobos (Runtime Library)"
>
> These are just ideas. I know you've put some time into the way you've set it up, but I'm not sure how easy to maintain it would be with the current convention.
>
> What do you guys think? I don't mind setting it up according to my convention if people like it.
>
On further thoughts...

You at least need to put the full names in the document itself, so we can know which are the DMD ones. We need to see amendments on those pages but have them grouped on the amendments page as well.  Why -

1) People will put ammendments on these pages if you don't tell them where to go.
2) A localised place is primarily for Walter so that he doesn't need to visit many pages.
3) I would like to see the amendments on the assoisated page.  I'm not going to go looking for them by going to the amendments page.
4) The actual admendment only needs to be written in one location but linked to by the other locations.

-- 
-Anderson: http://badmama.com.au/~anderson/

J C Calvarese wrote:

> J Anderson wrote:
>
>> Walter wrote:
>>
>>> Sounds like a fine idea to me. Set up the wiki pages, and I'll add the
>>> links. The documentation can certainly use improvement.
>>>  
>>>
>> Ok, you can find all the pages at:
>> http://www.prowiki.org/wiki4d/wiki.cgi?Digital_Mars_Comment
>>
>> However please use the direct links as nobody likes going though multiple pages to get somewhere.
>
>
> Joel and everyone,
>
> I have some suggestions.
>
> I'm not sure why you've added the new sections rather than adding to the existing DocumenationAmendments section (I think Helmut added it for this purpose). Instead of having two competing wiki sections
> (DocumentationAmendments and Digital_Mars_Comment) perhaps we should just have one. If DocumentationAmendments is too verbose, we can delete that and recreate it as DocComments or DocumentComments.
>
> Also, instead of having separate pages, we could have subpages:
> DocComments/Arrays
> DocComments/Phobos
>
> I think it'd be helpful if the wiki page corresponded with the HTML filename (the filenames are shorter and probably less likely to change):
>
> abi.html    -> DocComments/ABI     "Application Binary Interface"
> intro.html  -> DocComments/Intro   "Introduction"
> phobos.html -> DocComments/Phobos  "Phobos (Runtime Library)"
>
> These are just ideas. I know you've put some time into the way you've set it up, but I'm not sure how easy to maintain it would be with the current convention.
>
> What do you guys think? I don't mind setting it up according to my convention if people like it.

Also links section should be about that specific topic (tutorials ect...).  For the links page I did pages of links as that seemed appropriate.

-- 
-Anderson: http://badmama.com.au/~anderson/

J Anderson wrote:
> J C Calvarese wrote:
> 
>> J Anderson wrote:
>>
>>> Walter wrote:
>>>
>>>> Sounds like a fine idea to me. Set up the wiki pages, and I'll add the
>>>> links. The documentation can certainly use improvement.
>>>>  
>>>>
>>> Ok, you can find all the pages at:
>>> http://www.prowiki.org/wiki4d/wiki.cgi?Digital_Mars_Comment
>>>
>>> However please use the direct links as nobody likes going though multiple pages to get somewhere.
>>
>>
>>
>> Joel and everyone,
>>
>> I have some suggestions.
>>
>> I'm not sure why you've added the new sections rather than adding to the existing DocumenationAmendments section (I think Helmut added it for this purpose). Instead of having two competing wiki sections
>> (DocumentationAmendments and Digital_Mars_Comment) perhaps we should just have one. If DocumentationAmendments is too verbose, we can delete that and recreate it as DocComments or DocumentComments.
>>
>> Also, instead of having separate pages, we could have subpages:
>> DocComments/Arrays
>> DocComments/Phobos
>>
>> I think it'd be helpful if the wiki page corresponded with the HTML filename (the filenames are shorter and probably less likely to change):
>>
>> abi.html    -> DocComments/ABI     "Application Binary Interface"
>> intro.html  -> DocComments/Intro   "Introduction"
>> phobos.html -> DocComments/Phobos  "Phobos (Runtime Library)"
>>
>> These are just ideas. I know you've put some time into the way you've set it up, but I'm not sure how easy to maintain it would be with the current convention.
>>
>> What do you guys think? I don't mind setting it up according to my convention if people like it.
>>
> On further thoughts...
> 
> You at least need to put the full names in the document itself, so we can know which are the DMD ones. We need to see amendments on those pages but have them grouped on the amendments page as well.  Why -

I'll put the "full title" on each comment page. That's not a problem.

But I'm confused. Aren't all of the comment pages "the DMD ones"? I thought the idea was to annotate the official documentation. We can talk about other documentation somewhere else on the wiki.

> 1) People will put ammendments on these pages if you don't tell them where to go.

What's the difference between an amendment and a comment? Can't they be the same? Aren't they often the same?

> 2) A localised place is primarily for Walter so that he doesn't need to visit many pages.

I'm all for making this easy for Walter.

> 3) I would like to see the amendments on the assoisated page.  I'm not going to go looking for them by going to the amendments page.

I'd like the see all of the corrections, amendments, anotations, and comments on the same page. They are similar concepts not easily differentiated.

> 4) The actual admendment only needs to be written in one location but linked to by the other locations.

Now I'm even more confused. The "amendments" show up twice? Once on the comment page and again on the amendment page? How about just once on the  comment page? I now there are too many pages on there right now. I'll delete the extras once I'm sure I'm not going to mess anyone up.

For what it's worth (perhaps nothing), I put a slick table up at http://www.wikiservice.at/d/wiki.cgi?DocComments to point out where I think all the pages should be. (Now the question is: "What's supposed to be on the pages?")

I think my brain has already shut down for the evening. Maybe this will all make sense to me in the morning. Sorry for the rambling.

-- 
Justin (a/k/a jcc7)
http://jcc_7.tripod.com/d/

J C Calvarese wrote:

> J Anderson wrote:
>
>> J C Calvarese wrote:
>>
>>> J Anderson wrote:
>>>
>>>> Walter wrote:
>>>>
>>>>> Sounds like a fine idea to me. Set up the wiki pages, and I'll add the
>>>>> links. The documentation can certainly use improvement.
>>>>>  
>>>>>
>>>> Ok, you can find all the pages at:
>>>> http://www.prowiki.org/wiki4d/wiki.cgi?Digital_Mars_Comment
>>>>
>>>> However please use the direct links as nobody likes going though multiple pages to get somewhere.
>>>
>>>
>>>
>>>
>>> Joel and everyone,
>>>
>>> I have some suggestions.
>>>
>>> I'm not sure why you've added the new sections rather than adding to the existing DocumenationAmendments section (I think Helmut added it for this purpose). Instead of having two competing wiki sections
>>> (DocumentationAmendments and Digital_Mars_Comment) perhaps we should just have one. If DocumentationAmendments is too verbose, we can delete that and recreate it as DocComments or DocumentComments.
>>>
>>> Also, instead of having separate pages, we could have subpages:
>>> DocComments/Arrays
>>> DocComments/Phobos
>>>
>>> I think it'd be helpful if the wiki page corresponded with the HTML filename (the filenames are shorter and probably less likely to change):
>>>
>>> abi.html    -> DocComments/ABI     "Application Binary Interface"
>>> intro.html  -> DocComments/Intro   "Introduction"
>>> phobos.html -> DocComments/Phobos  "Phobos (Runtime Library)"
>>>
>>> These are just ideas. I know you've put some time into the way you've set it up, but I'm not sure how easy to maintain it would be with the current convention.
>>>
>>> What do you guys think? I don't mind setting it up according to my convention if people like it.
>>>
>> On further thoughts...
>>
>> You at least need to put the full names in the document itself, so we can know which are the DMD ones. We need to see amendments on those pages but have them grouped on the amendments page as well.  Why -
>
>
> I'll put the "full title" on each comment page. That's not a problem.
>
> But I'm confused. Aren't all of the comment pages "the DMD ones"? I thought the idea was to annotate the official documentation. We can talk about other documentation somewhere else on the wiki.
>
>> 1) People will put ammendments on these pages if you don't tell them where to go.
>
>
> What's the difference between an amendment and a comment? Can't they be the same? Aren't they often the same?
>
>> 2) A localised place is primarily for Walter so that he doesn't need to visit many pages.
>
>
> I'm all for making this easy for Walter.
>
>> 3) I would like to see the amendments on the assoisated page.  I'm not going to go looking for them by going to the amendments page.
>
>
> I'd like the see all of the corrections, amendments, anotations, and comments on the same page. They are similar concepts not easily differentiated.
>
I see comments as extended help not nessary of official document quality, ie this doesn't work currently but you can do this.  Or here's something cool you can do.  Admendements are for typos and important details.

>> 4) The actual admendment only needs to be written in one location but linked to by the other locations.
>
>
> Now I'm even more confused. The "amendments" show up twice? Once on the comment page and again on the amendment page? How about just once on the  comment page? I now there are too many pages on there right now. I'll delete the extras once I'm sure I'm not going to mess anyone up.
>
> For what it's worth (perhaps nothing), I put a slick table up at http://www.wikiservice.at/d/wiki.cgi?DocComments to point out where I think all the pages should be. (Now the question is: "What's supposed to be on the pages?")
>
> I think my brain has already shut down for the evening. Maybe this will all make sense to me in the morning. Sorry for the rambling.
>
Because then Walter will have 48 pages to scan for admendements :(  Just one extra page with a list of pages that have amendments would be fine.

-- 
-Anderson: http://badmama.com.au/~anderson/

J Anderson wrote:
> J C Calvarese wrote:
> 
>> J Anderson wrote:
...
>>
>> I'd like the see all of the corrections, amendments, anotations, and comments on the same page. They are similar concepts not easily differentiated.
>>
> I see comments as extended help not nessary of official document quality, ie this doesn't work currently but you can do this.  Or here's something cool you can do.  Admendements are for typos and important details.

The important stuff will probably still get posted here or at the Bugs newsgroup. I think that will remain to be the most likely way to get Walter's attention.

> 
>>> 4) The actual admendment only needs to be written in one location but linked to by the other locations.
>>
>>
>>
>> Now I'm even more confused. The "amendments" show up twice? Once on the comment page and again on the amendment page? How about just once on the  comment page? I now there are too many pages on there right now. I'll delete the extras once I'm sure I'm not going to mess anyone up.
>>
>> For what it's worth (perhaps nothing), I put a slick table up at http://www.wikiservice.at/d/wiki.cgi?DocComments to point out where I think all the pages should be. (Now the question is: "What's supposed to be on the pages?")
>>
>> I think my brain has already shut down for the evening. Maybe this will all make sense to me in the morning. Sorry for the rambling.
>>
> Because then Walter will have 48 pages to scan for admendements :(  Just one extra page with a list of pages that have amendments would be fine.

Okay. I understand better now. I still think there are some flaws in this plan.

1. Rules will be broken.
Just because we make up a bunch of rules for people to follow when they're amending doesn't mean that anyone will follow them.

2. We're talking about volunteers.
I like to follow rules, but I'm not getting paid to do any of this. People will only jump so many hoops for free. I think we're putting up too many obstacles for contributions.

3. Does my definition of amendment match yours?
I still think it's hard to distinguish between an amendment and a comment. I'm hoping that the comments will be of such high quality that they would ALL add value if they were added to the official documentation. (Yes, I know I'm dreaming.)

4. Is Walter going to actually look at the amendments page?
Just because I'm adding to the amendments page doesn't mean that Walter's seeing it. I think the 3-alarm documentation bugs will continue to appear on newsgroups first and foremost. I was thinking maybe he'd glance at the comment pages occassionally and integrate stuff from there, but I guess there will be a lot of pages from which to choose. And many of them might be blank. I suppose he might be able to keep his eye on http://www.wikiservice.at/d/wiki.cgi?browse=RecentChanges like the rest of us. (Yes, I know I'm dreaming again.)

I won't stand in your way on this, but I'm still not certain it can work.

-- 
Justin (a/k/a jcc7)
http://jcc_7.tripod.com/d/

Trac (http://projects.edgewall.com/trac/) uses a wiki and you can get an RSS feed on Wiki changes.  That way, someone can police the masses as they make changes.

I'm thinking about using it at dsource.org after demmegod's suggestion.  Thought it might help here.

BA

J C Calvarese wrote:
> J Anderson wrote:
> 
>> J C Calvarese wrote:
>>
>>> J Anderson wrote:
> 
> ...
> 
>>>
>>> I'd like the see all of the corrections, amendments, anotations, and comments on the same page. They are similar concepts not easily differentiated.
>>>
>> I see comments as extended help not nessary of official document quality, ie this doesn't work currently but you can do this.  Or here's something cool you can do.  Admendements are for typos and important details.
> 
> 
> The important stuff will probably still get posted here or at the Bugs newsgroup. I think that will remain to be the most likely way to get Walter's attention.
> 
>>
>>>> 4) The actual admendment only needs to be written in one location but linked to by the other locations.
>>>
>>>
>>>
>>>
>>> Now I'm even more confused. The "amendments" show up twice? Once on the comment page and again on the amendment page? How about just once on the  comment page? I now there are too many pages on there right now. I'll delete the extras once I'm sure I'm not going to mess anyone up.
>>>
>>> For what it's worth (perhaps nothing), I put a slick table up at http://www.wikiservice.at/d/wiki.cgi?DocComments to point out where I think all the pages should be. (Now the question is: "What's supposed to be on the pages?")
>>>
>>> I think my brain has already shut down for the evening. Maybe this will all make sense to me in the morning. Sorry for the rambling.
>>>
>> Because then Walter will have 48 pages to scan for admendements :(  Just one extra page with a list of pages that have amendments would be fine.
> 
> 
> Okay. I understand better now. I still think there are some flaws in this plan.
> 
> 1. Rules will be broken.
> Just because we make up a bunch of rules for people to follow when they're amending doesn't mean that anyone will follow them.
> 
> 2. We're talking about volunteers.
> I like to follow rules, but I'm not getting paid to do any of this. People will only jump so many hoops for free. I think we're putting up too many obstacles for contributions.
> 
> 3. Does my definition of amendment match yours?
> I still think it's hard to distinguish between an amendment and a comment. I'm hoping that the comments will be of such high quality that they would ALL add value if they were added to the official documentation. (Yes, I know I'm dreaming.)
> 
> 4. Is Walter going to actually look at the amendments page?
> Just because I'm adding to the amendments page doesn't mean that Walter's seeing it. I think the 3-alarm documentation bugs will continue to appear on newsgroups first and foremost. I was thinking maybe he'd glance at the comment pages occassionally and integrate stuff from there, but I guess there will be a lot of pages from which to choose. And many of them might be blank. I suppose he might be able to keep his eye on http://www.wikiservice.at/d/wiki.cgi?browse=RecentChanges like the rest of us. (Yes, I know I'm dreaming again.)
> 
> I won't stand in your way on this, but I'm still not certain it can work.
> 

Arcane Jill schrieb:

> It would be nice to doxygenate the Phobos functions - but I suspect you need the
> source code for that.

What makes you think that we don't have the source?

-eye