[Pdweb] please put the dev docs back

Hans-Christoph Steiner hans at eds.org
Tue Sep 26 21:56:30 CEST 2006


On Sep 26, 2006, at 6:26 AM, IOhannes m zmoelnig wrote:

> hi
>
> Hans-Christoph Steiner wrote:
>> I just noticed that the developer docs on puredata.org were moved  
>> to the "developer" section.  Please put them back where they were,  
>> that is where they belong.  The "developer" section is not for  
>> documentation, the documentation section is.  That has been long  
>> since established.
>> Also, there are many, many links out there that point to the old  
>> location for the developer docs.
>> Lastly, please consult this list before making such drastic  
>> changes to the website.  I've put a lot of work into that section,  
>> so you could have at least asked.
>
> i admit it was really bad practice, esp. not to ask.
>
> but before i put this back, could we clarify:
> why is "documentation" the place where it belongs? or: what makes  
> the "developer" section less "the right place"?
>
> the thing i currently see is, that there are 2 branches /dev and / 
> doc/dev which both hold documentation about development.
>
> information is surely to be in the directory where you are  
> currently not looking, since it is unclear, where it should be.  
> (and i am not the only one who feels like this).
>
> after all, the /dev section IS "documentation about development",  
> and not "development" itself.

By that standard then everything on the web is documentation.  We are  
using a narrower definition which makes a lot more sense.  Manuals,  
HOWTOs, tutorials, these are documentation.  Everything in /docs/ 
developer was a HOWTO, manual, or tutorial

The developer section is meant for developer tools: key links,  
bugtrackers, wikis for project management, etc.  The content in the  
wikis will probably ultimately end up being boiled down to docs, but  
they are not there yet.  The bugtracker is documentation on bugs, but  
it is not a manual, howto, or tutorial.

Please read the archives for a more in depth discussion.

> so in theory(!) i see no reason to have 2 separate branches with  
> the same topic but different content.
>
> however, you are completely right: in practice there are external  
> links pointing to the old & deprecated location, which must be  
> handled.
> the good thing is, that this could be handled very easily: i can  
> set up a rewrite rule on the webserver, so that http://puredata.org/ 
> doc/dev is automatically redirected to http://puredata.org/dev  
> which should make all the links valid again.

We discussed this stuff at length when we set up the website (check  
the archives).  Its been working well as far as I've seen.  I see no  
reason to change it now.


> and finally: please use relative linking whenever possible.
> there is really no point in linking from http://puredata.org/bi/ba  
> to "https://www.puredata.info/bi/borg" when "borg" would have done  
> the same.

Yes indeed, that's just a general rule in web site building.

> mfga.dsr
> IOhannes
>
> why i didn't ask? because we are really bad at decision-making.  
> most discussions stop at the point where "everybody" (this is: you,  
> me, probably a single 3rd person) has clarified their poisition.

It takes 10 seconds to send such an email.  It would have saved us  
all a lot of time and hassle.

.hc

------------------------------------------------------------------------

Computer science is no more related to the computer than astronomy is  
related to the telescope.      -Edsger Dykstra





More information about the pdweb mailing list