On Fri, Aug 29, Klaas Freitag wrote:
I don't mind reading source code to document, but I plainly don't have the time to document openSUSE BuildService. I don't find lots of time to document my own stuff, so why should I do so for things others made? If that's your mindset you should think again if free software projects are the right place for you to be. Especially if these others are an commercial company. This opinion, again, is the reason for many problems we have in the project. It's poor.
Although I do exactly know, why documentation is often lacking in many free software projects, I think a projects owner cannot expect it's users to document the project. To document a project, a user has to have the knowledge of the project creator or a developer with deep knowledge. Or the user has to spend a lot of time to dig into that project. You cannot expect that from most of the users. So if the intent of a free software project is to spread fast, it should at least have basic documentation. [...]
What is needed is an "OBS reference manual". Ideally, it should be included in the source repository and all changes to OBS should include updates to the documentation as well (a "live" document). There are tons of examples of other open source projects doing this and plenty of tools out there that support doing it. Again I agree completely. Maintaining the documentation in the source repo is the only way to produce documentation that goes along the product.
But to write good user documentation about the BS it requires more than just having it in the source repo. Such a documentation needs professional editing, a good concept, ongoing proofreading etc.
[...] Well, I don't think so. Incomplete or bad documentation is always better then no documentation at all. It's like bad press is better then no press... :-) -- With best regards, Carsten Hoeger