[generguide-devel] Re: I've created Generic Guide project

[Cameron S. <ca...@sh...>]

On Wednesday 18 Jun 2003 2:00 pm, you wrote:
> > Hope you are not feeling as sick as you were on the IRC meeting.
>
> Yes, I am much better now. Monday (in Europe) was the worst day.
Glad to hear that.

> > My plan is to:
> > * Work out a process for importing the generguide into the geotools
> > project. Any ideas?
>
> It depends what you exactly mean when you talk about importing. I am not
> sure yet how do you expect generic documentation should be used.
> For example generic guides can be used as templates. And projects can
> create own documentation based on these templates. Than with some set of
> XSLT or scripts in some language they generate own documentation inserting
> project logo, addresses of mailing lists, developer list  and so on... in
> proper place in documentation.
>
> Another approach is to use generic guides as references or patterns. So on
> project page they can say "In our project development we follow standards
> presented on "genericguide" project site." And maybe than there is no need
> to physicaly importing documentation.
>
> In real use I can see both approaches. Some parts of guide can be used as
> templates and some of them as references or patterns.

Yes, I can see both those working.
The way the current generguide/bin/build.sh script works is:

cp generguide/docs $tmp
cp project/docs $tmp #overwriting generguide/docs
style $tmp > $target/developersguide.html

I was thinking that geotools would import generguide into it's docs (or 
developersguide) directory, then create a new directory for geotools specific 
sections.
Eg:
geotools/geotools-src/developersguide/generguide/...
geotools/geotools-src/developersguide/localdocs/*.sgml

This avoids the need for XSLT.  However I'm possibly avoiding XSLT because I 
don't know enough about it and am going with what I know instead.

>
> > What directory should it sit in?
>
> I think existing geotools "docs" directory is good.

ok.

>
> > * Remove references in the generguide to geotools.
> > * At the same time, create local geotools specific sections in geotools
> > cvs. * Announce the project to the world.  (Probably via email lists like
> > maven-user).  Any suggestions on where the project should be announced?
>
> When I started my own project I was announcing it on many developers
> specific places like java.sun.com in developers section, IBM alphaworks,
> on some related discusion news list.
> This project is very special. I think there are many people who could be
> very interested in such info.
> I will think about some more appropriate places.

ok.

>
> > If you are interested in helping out with any of this then I'd be
> > delighted to have you on board.  However if you are sick, or have
> > something better to do then that is fine too.
>
> I would be happy to take care about some task. The more there will 4 free
> days from tomorrow in Poland. However I am not sure if I will go to Gdansk
> to my family for this time. If I stay at home I can spend all the time on
> it (few hours I need for GeoTools VPF). The decision will be known tommorow
> in the morning ;). And than I don't know what will be next week. Again if
> my family will come back to me to Warsaw I will be having less time for OS
> projects. If not, you can use all my evenings time.

That is very generous of you.  However your family is much more important than 
a computer project, so I hope you don't make decisions based on this work.

>
> And from 15.07 to 30.07 I have holydays and probably will be away from
> computer. However from the beginning of August I expect again to have more
> time.

ok.

>
> I have looked in CVS repository and wondered why did you put docbook xslt
> there? From time to time it is new version released and I expect each next
> version will be better than former. Maybe it should be used as external
> library?

I put it here to ensure the build.sh script works.  The users computer might 
not have xslt installed.  I was trying to ensure that there is minimal 
configuration required to get generguide working.

Doc format:
I've been thinking about setting the structure of the developersguide in the 
following format:
http://generguide.sourceforge.net/developersguide/developersguide.html#writingguidelines
Process
  sentence or 2 explaining process
  Tool1
    sentence or 2 explaining tool
    Section 1 about tool
      possible sentence explaining section.
      rest of section
    Section 2 about tool
  Tool2
    ...
Reference

The rules are not hard and fast because not all documentation will fall into 
this pattern.

Tasks:
If you are looking for something to do, I'd suggest going through each section 
and doing the following:
1. Restructure to above format.
2. Remove all references to geotools and GT2.  A lot of the time, you can 
replace "geotools" with "this project".
3. For sections that are geotools specific:
3.1 make a copy of the section in the geotools repository, say 
geotools-src/docs/localdevelopersguide/
3.2 Either remove section from generguide or replace with CAPITALISED GENERIC 
WORDS which will need to be edited later by specific projects.
4. Make sure all sections have unique id tags associated with them.

I'd suggest that you start with your emacs sections.

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