[marhamat]

Hi Alberto

At first i should say that Documentation project is a very good idea and i appreciate that.like you i think that need to be improved because of some reasons which i note them here briefly:

1)New users who are not familiar with Openfoam and want to start learning it,will get in trouble and be confused because the references which they need in,are not concentrated.

2)So many attempts are repeatetive,on the other words,there are some persons who are trying in a ceritan problems which was solved by another person at last.i think shortage of good announcement in the site,is the main reason for that.

3)There are so many users who are not at the same level.i think if we classify the users who are at the same level in groups,then we have groups where users at the same levels are there and i think they can consult,disscuss and understand each other beter.whenever users in one group find a problem which is unsolvable for them,then they can get help from another group with the higher level

Maybe there be so many good ideas from various users,but i think implementation of these ideas need a very good management,experience and much attempts.so i think there should be some capable and hardworking persons who accept responsibilities to do that.....the other users can help these responsible persons by their good ideas.

Best regards.
Marhamat

[grtabor]

I've been following this discussion with some interest. I'm not sure that adding another way of discussing the work is the way to go. For my money, a useful addition would be to improve the documentation in the header files, so that when doxygen is run on them, it produces something useful. Currently, because there is so little info in the header files, doxygen really only generates structural information about the classes (a list of member functions, but no real information about what any of them do; inheritance diagrams which are very complicated, and so forth). doxygen is never going to work that well because some of the most important classes are templated, but it could be improved.

The problem with this is how to organise it. The guys at OpenCFD are not likely to do this unless there is some revenue stream associated with it (not unreasonable!); and organising the documentation of the code (and keeping it up to date) would be very difficult - in fact I'm not sure how togo about doing it. Any suggestions?

Gavin

[olesen]

Hi Gavin,

I'm just caught up with the discussion and I think you have correctly recognized the problem.
For any reasonable improvement, people must be willing to invest a bit of money for OpenCFD to write additional documentation. With some funding, I'm quite certain that OpenCFD has a suitable and (like the rest of the code) high quality solution.

Even if a voluntary effort could be properly coordinated and yielded *lots* of documentation, I don't see that the OpenCFD guys can (or should) donate piles of their time to assess and correct possibly erroneous documentation.

Perhaps what could be organized is a pledge list in which people list their documentation priorities and how much money they can commit to seeing it realized.

If people cannot commit money (or don't wish to), then the pledge list could represent a commitment to fully document a particular aspect of OpenFOAM. I assume that the existing wiki structure should be adequate to hold such documentation at first.

[alberto]

Documenting the headers is a nice idea. The main issue are how to put documentation into released headers, and how to maintain it. It's difficult to do this without the involvement of OpenCFD.

Mark, are you thinking to something similar to paraview, which offers free software and sells the documentation manual?

Regards,
Alberto

[deinstein]

Hi,

My two cents are that the Paraview model is not a bad one at all. It not only generates revenue for the developers, as is appropriate, but also motivates good documentation.

Dan

[olesen]

Hi Alberto,

I don't think the vtk book model works here. They have a really large user base, govt funding etc. The number of OpenFOAM books that could sold compared to the hours of documentation effort would result in a very expensive book indeed.
If anyone thinks they can make much money writing such a book, I suppose we might have seen it already.

[deinstein]

Well, that brings up a good question. Has anyone quantified how big or small hte OF user base is?

[alberto]

Hi Mark,
that's exactly what I think. I asked the question to better understand your idea.

Paraview is an application, while OpenFOAM is an extremely big toolkit and a full documentation would be a huge work and would require a lot of time and money to support it.

I like the idea of on-request documentation financially supported by the community. But it all depends on how much the community can/wants to invest. Many are academic users or students (myself too), so I don't expect much.

In my opinion, the first step would be to create a guide for newcomers, which is what I consider the lacking ring. In my view it should be something to allow newcomers to write their _simple_ solvers by themselves, without having to dig into the wiki, the discussion board, theses, and other information sources. For advanced needs, of course there's commercial support from OpenCFD.

Regards,
Alberto

[olesen]

Hi Alberto,

I think you've got the idea. If people want specific documentation, or documentation in general, they need either need to fund it or be writing it themselves.

To be quite provocative: if people *really* wanted to have better documentation, the wiki would already be bursting full of information.

Your point about the documention dimension of an application vs. OpenFOAM is also a very good one.
Whereas the documentation of a particular CFD application (Fluent, Star-CD etc) is typically divided into "Methodology" (equations and models being solved) and the "User Guide" (how to service the software), OpenFOAM would need a "How-To" and "Why is it so". Both of which are considerably more arduous to write.

[alberto]

Hi Mark,
I don't fully agree on your comment about the wiki. We have to consider the composition of the OF user base. There are experienced users, with a strong CFD background and a good knowledge of numerics and programming techniques, and there are new or basic users, who are looking for a tool to do their work/research and to implement their models.
The first group is probably not interested in writing documentation, because they already did the effort to learn OF by themselves, and it would require a lot of time. The second group needs documentation, but of course can't write it because of lack of knowledge and experience.

I think it's possible to do a decent work on documentation _only_ creating a mixed group of experienced and unexperienced users who will invest some of their time and efforts in it, working together and with common goals. If everything is left to individuals I don't think it's going to work.

Regards,
A.

Here are my two cents.

About the IRC channel,

Some of us in the linux community have found that the IRC is a great tool to ask and answer simple questions. Its not a good medium for indepth discussions however. It serves as a mechanism to keep the forums/mailing lists free of FAQs making the forums and mailing lists easier to search through. The IRC is also a good place to direct people to the indepth discussions of a topic instead of staring a new thread and dispersing the discussion.