About Documentation at OpenCSW


There are 6 places for documentation at OpenCSW:

Editing documentation

This document:


Each documentation location has own user name space, unfortunately. If you’re a maintainer and you don’t have permissions to edit the wikidot wiki, set up an account on wikidot.com and write to maintainers@ or ask on the IRC channel to get your user added to the project.

If you’re a maintainer and you notice something wrong or missing in any of the above places, don’t leave it broken! If you’re not sure what’s supposed to be in the given piece of documentation, ask on the maintainers@ mailing list or on IRC.

No documentation is better than wrong documentation

If you notice a piece of documentation that you know is incorrect or obsolete, DELETE IT. Yes, really! Even if you don’t know what’s supposed to be there, and deleting is the only thing you can do.

Don’t be concerned about losing content ‒ wikis and wordpress are versioned, and so is the source code repository. We can always recover content if we need to. Once you’ve deleted the offending piece of text, ask on maintainers@ or IRC about given topic and if it’s worth documenting, write it down in an appropriate place (may not be the place where you originally found it).

Moving documentation

If a piece of documentation is in a wrong place, move it to the right place. For example, if you notice the catalog format documentation on the wiki, you can immediately see that it’s in a wrong place. The catalog format is practically unchanging and therefore should go into the less frequently changing, more polished section: the manual. Use common sense, if in doubt, ask on maintainers@.

When you’re moving a piece of documentation, create a link from the old place to the new place, so that web spiders and humans can still find their piece of documentation, starting at the old location.

What should not be documented?

If relevant source code is easy to read, just link to the code.

For example, it doesn’t make sense to create a document with a list of our RESTful URLs. We can link directly to the source code, which is just as easy to read, and is less likely to be incorrect.

Instead, you can describe how to find things out.