[csw-maintainers] Documentation: 4 places and their use

[Maciej (Matchek) Bliziński]

“For historical reasons”, FHR in short.

Here are some places where we have documentation:

- http://wiki.opencsw.org - mainly for ongoing projects because it's easy
to edit
- http://www.opencsw.org/manual/ - which we intend to be “the opencsw book”
which is supposed to be carefully written and reviewed and all
- https://sourceforge.net/apps/trac/gar/ - for GAR documentation
- http://www.opencsw.org/use-it/ - for official project information

We also have the archive of old content formerly known as “standards” or
“packaging standards”:
https://gar.svn.sourceforge.net/svnroot/gar/csw/mgar/pkg/opencsw-manual/trunk/files/archive.txt

It doesn't seem like we'll be closing down any of these sites, but I think
we should have a generally agreed opinion about what is kept where, and try
to make more order in our docs.

Take these pages for example:
http://www.opencsw.org/manual/for-maintainers/buildfarm-setup.html
http://wiki.opencsw.org/buildfarm
http://wiki.opencsw.org/checkpkg

They are mostly about the same thing. Since this particular part of
documentation is largely unchanging, in my opinion it should go into the
manual.

In the deep past, we were pretty calcified as far as moving documentation
is concerned. These days it's easier to make changes, so I would like to
propose the following:

- have a rough agreement about places for documentation and where we keep
what type of docs
- advertise that we as a community are OK with people making changes to
documentation, e.g. moving things around
- provide a rough guideline, mostly stating the common sense things like
"if you move content from place A to place B, make a link from A to B so
people can still find the stuff you've moved"

Thoughts?

Maciej
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.opencsw.org/pipermail/maintainers/attachments/20130426/b4c5ad30/attachment.html>