discuss: Thread: Generic Software Developers Guide

I'm currently writing a Software Developers Guide for a java based project:
http://geotools.org/gt2docs/

What I am noticing as I write it is that 90% of it is generic and could be cut 
and paste verbatum into another project.  Eg:
* Licence
* ConfigurationManagementProcess
* BuildProcess
* CodingStandards
* UnitTesting
* DirectoryNamingConvensions
* DocumentationProcess
etc.

So I'm proposing setting up a Generic Guides project.  It would contain a 
number of docbook sections which address one part of the software development 
process (Eg CVS for code control).  Some processes can be addressed 2 
different ways, so there would be 2 sections and the user can select the 
process they want (Eg C_Coding_Standards.sgml or Java_Coding_Standards.sgml).

One master document would pull in all the subsections using <xi:include> tags.

Later, we could write a wizard to help users select sections for each process 
they need to address.

So my questions are:
1. Is anyone working on something similar to this?
2. Should this be done under the umbrella of the LDP or should I set up a 
seperate sourceforge project for it?

-- 
Cameron Shorter              http://cameron.shorter.net
Open Source Developer        http://mapbuilder.sourceforge.net
Software Engineer/Team Lead  http://www.adi-limited.com/

 > 1. Is anyone working on something similar to this?

I have a detailed article on C++ coding guidelines.  It is not under a Free 
license, but I've been considering re-licensing it that way.  The reason I 
haven't yet is that it draws a lot of traffic to my website, which is valuable 
to my consulting business.  On the other hand, I would like it to benefit more 
people than might stumble across it on my site:

    Pointers, References and Values
    http://www.goingware.com/tips/parameters/

Regards,

Mike
-- 
Michael D. Crawford
GoingWare Inc. - Expert Software Development and Consulting
http://www.goingware.com/
####@####.####

      Tilting at Windmills for a Better Tomorrow.

Hi Mike,

Is there any chance this would fit well with the C++ documentation we
are currently reworking?  I am wondering if it is outside the scope
(team members speak up please!) and could be incorporated into a section
of the new C++ HOWTO, with you added as a contributor.  The subject of
coding standards sounds like something that would fit well here.

On the other hand, if everyone is of the opinion that it should remain
separate, that's fine.  

If you wanted to do this, it would be under the GFDL which sounds okay
if I'm not mistaken?

What do you (and everyone else) think?  :)

Tabatha

On Fri, 2003-01-10 at 18:33, Michael D. Crawford wrote:
>  > 1. Is anyone working on something similar to this?
> 
> I have a detailed article on C++ coding guidelines.  It is not under a Free 
> license, but I've been considering re-licensing it that way.  The reason I 
> haven't yet is that it draws a lot of traffic to my website, which is valuable 
> to my consulting business.  On the other hand, I would like it to benefit more 
> people than might stumble across it on my site:
> 
>     Pointers, References and Values
>     http://www.goingware.com/tips/parameters/
> 
> Regards,
> 
> Mike
-- 
Tabatha Persad
Web: www.merlinmonroe.com
Linux Documentation Project Review Coordinator (http://www.tldp.org)
Gnu Writing Movement Contributor (http://gwm.gnu.org)
Linux Counter Area Manager US:wa (http://counter.li.org)

On Fri, Jan 10, 2003 at 07:00:03PM -0800, Tabatha Persad wrote:

> Is there any chance this would fit well with the C++ documentation we
> are currently reworking?  I am wondering if it is outside the scope

As I said to Michael earlier, I think his (pretty useful) document is
fine just where it is.

regards
john

Tabatha asked:
 > What do you (and everyone else) think?  :)

I'm willing to release the document under the GFDL if the result of that would 
have as much of an effect of promoting my consulting business as having the 
only copy on my website does.  I have some other documents under the GFDL.

I realize there's no real way to predict that for sure.

I apologize for being so openly mercenary about it, but I earn my keep solely 
through my business, and times have been tough these last couple years.

On the one hand, people find the existing document via links and search 
engines, come to read the only copy of the article, and sometimes stay to visit 
the rest of my site, where they find out I'm a consultant.  Also sometimes they 
give me a link, which drives up my search engine rankings.

On the other hand, I realize that having the document on the LDP's website and 
included in Linux distributions would cause more people to read it, who would 
see that I wrote it, and who would therefore (hopefully!) regard me as an 
expert C++ programmer, and then come find me if they need a consultant.  But I 
might not get so many links to my own site.

I felt that John Levon had a good point when he said the the document was best 
where it is, which is why I didn't pursue Free licensing anymore after I 
initially brought it up in my Advogato diary.

I'm quite open to listening to arguments about it though.  I would like to 
benefit more programmers by opening it, but it's probably the most popular page 
on my site.

Here are the pieces I already have under the GFDL:

http://linuxquality.sunsite.dk/articles/
http://www.goingware.com/zoolib/cookbook/  (This isn't nearly finished yet)

Here's another article you may be interested in, which is not Free but I am 
considering making so:

Writing Cross-Platform Software - Getting Started
http://www.byteswap.net/mikesnotes/2002/getting-started/

Regards,

Mike
-- 
Michael D. Crawford
GoingWare Inc. - Expert Software Development and Consulting
http://www.goingware.com/
####@####.####

      Tilting at Windmills for a Better Tomorrow.

On Saturday 11 Jan 2003 2:33 am, Michael D. Crawford wrote:
>  > 1. Is anyone working on something similar to this?
>
> I have a detailed article on C++ coding guidelines.  It is not under a Free
> license, but I've been considering re-licensing it that way.  The reason I
> haven't yet is that it draws a lot of traffic to my website, which is
> valuable to my consulting business.  On the other hand, I would like it to
> benefit more people than might stumble across it on my site:

While I'd love to see you open source your guide, it is not necessary.  I've 
kept my guidelines simple and my coding standards simply refer to Sun's Java 
Coding Standards.

-- 
Cameron Shorter              http://cameron.shorter.net
Open Source Developer        http://mapbuilder.sourceforge.net
                             http://geotools.sourceforge.net
Software Engineer/Team Lead  http://www.adi-limited.com/

"Michael D. Crawford" wrote:
> 
>     Pointers, References and Values
>     http://www.goingware.com/tips/parameters/
> 

Michael,

I spent two hours trying to find out why my web spider could not
download your files correctly. I started fantasizing you would have some
highly effective web robot detection script on your web server which
would mangle the files. I kept getting errors of the type "file has zero
size". 

It turned out it has to do with gzip encoding. As soon as I turned off
"use gzip encoding for transfer", I was able to download the files for
later reading. 

I thought I would rather let you know - perhaps it's a problem with your
web server, 'cause I've never had to disable that option till now. 


-- 
Regards

Chris Karakas
http://www.karakas-online.de

"Michael D. Crawford" wrote:
> 
> On the other hand, I realize that having the document on the LDP's website and
> included in Linux distributions would cause more people to read it, who would
> see that I wrote it, and who would therefore (hopefully!) regard me as an
> expert C++ programmer, and then come find me if they need a consultant.  But I
> might not get so many links to my own site.
> 

You could put a line saying "The latest version of this document can be
found at www.goingware.com, together with other goodies you might be
interested in - give me a visit!"

Each time read a HowTO I was interested in and had a similar remark, I
visited the site immediately ;-)

I don't think this is unethical/non-free/negative - what do the others
think?

-- 
Regards

Chris Karakas
http://www.karakas-online.de

Chris,

I expect the problem you had with gzip encoding is some misconfiguration on the 
part of my hosting service.  http://www.seagull.net/ is very responsive to 
support requests, I'll ask them about it.

Your suggestion of pointing back to my website from the HOWTO is a good point. 
  I would like to know what others think of it.

Regards,

Mike
-- 
Michael D. Crawford
GoingWare Inc. - Expert Software Development and Consulting
http://www.goingware.com/
####@####.####

      Tilting at Windmills for a Better Tomorrow.

Great suggestion, Chris!  When I read a HOWTO I also usually visit the
web site of the author, to poke around as well as make sure I read the
latest version of the doc.

I think many authors would agree on that, and I think it's a very
positive and ethical way to get traffic!

Tabatha

On Sat, 2003-01-11 at 17:58, Chris Karakas wrote:
> "Michael D. Crawford" wrote:
> > 
> > On the other hand, I realize that having the document on the LDP's website and
> > included in Linux distributions would cause more people to read it, who would
> > see that I wrote it, and who would therefore (hopefully!) regard me as an
> > expert C++ programmer, and then come find me if they need a consultant.  But I
> > might not get so many links to my own site.
> > 
> 
> You could put a line saying "The latest version of this document can be
> found at www.goingware.com, together with other goodies you might be
> interested in - give me a visit!"
> 
> Each time read a HowTO I was interested in and had a similar remark, I
> visited the site immediately ;-)
> 
> I don't think this is unethical/non-free/negative - what do the others
> think?
-- 
Tabatha Persad
Web: www.merlinmonroe.com
Linux Documentation Project Review Coordinator (http://www.tldp.org)
Gnu Writing Movement Contributor (http://gwm.gnu.org)
Linux Counter Area Manager US:wa (http://counter.li.org)