CFD Online Discussion Forums

CFD Online Discussion Forums (https://www.cfd-online.com/Forums/)
-   OpenFOAM (https://www.cfd-online.com/Forums/openfoam/)
-   -   Roadmap for new releases (https://www.cfd-online.com/Forums/openfoam/61034-roadmap-new-releases.html)

gschaider May 24, 2005 12:20

Thanks :-) About the docume
 
Thanks :-)

About the documentation: I don't know how the documentation is currently maintained (I could tell, that it was not done with Word, because the formulas look good in it).

It's not that I'm unwilling to do this it's just that I think that there is a problem in principle: a document in LaTex assumes a linear structure. Web-Pages generated from a LaTeX-document will therefor always have a tree-like structure (if we don't look at cross-references). The Wiki on the other hand assumes no structure whatsoever. Everything can be linked with everything. It's no problem to map the structure of a LaTeX-document to a Wiki, but the other way round could be difficult (needs hand-editing and/or great disciplin from the people involved). What I'm trying to say is: I think the quality of the printed documentation would suffer.

But I'll loook into that matter.

Until then my idea (as materialized in the Wiki :-) ) was to have a parallel structure in the form of the Addenda where people add their contributions to the documentation. An editor-person can then harvest this via copy-and-paste into the definitve documentation.

henry May 24, 2005 12:25

I agree with your reservations
 
I agree with your reservations about using the Wiki as a method for developing the documentation directly and your proposal in the last paragraph which fits with our (OpenCFD's) plans for the development of the formal documentation.

gschaider May 24, 2005 19:19

Please excuse me, if I am gett
 
Please excuse me, if I am getting too philosophical here. It's late.

I think there is a distinction between information and knowledge. To me information is the collection of bits of information (sorry didn't find a better word) that may be ordered in some way. Knowledge is when one can see these informations as a whole. When someone has knowledge he can tell it to others in one narrative.

To me a Wiki is about information. A manual (if it's not just written because of contractual obligations) is about knowledge.

That said, I'd like to say, that I liked the two OpenFOAM manuals very much (my main reservation is that the "Programmer's Guide" was a bit misleading; but that has been said elsewhere by more qualified people in this message board). I wouldn't say, that I read every page of them, but someone thought about a structure and if I skipped a part I could tell what I skipped (because of the narrative).
With hypertext (==Wiki) there's always the problem that you're not always sure if the parts you didn't click on were important (to you).

The purpose of a Wiki can therefor only be to acquire information from as many sources as possible.
Knowledge can only be gathered by two ways (please don't take the the political classifications by face value):
a) looking at all the information an deducing the knowledge by yourself (the anarchistic way)
b) let someone write a book of knowledge, read it and believe parts of it (the facistist/stalinist way)

I think that most of us (academically trained people) went from b) to a). ( a. only is possible, but very time consuming)

Sorry. I got carried away.
Executive summary: Bernhard thinks that Wiki is good, good manual is better. Wiki can help with manual (but is no substitute).

smith May 25, 2005 09:52

Hi Bernhard, For editing a
 
Hi Bernhard,

For editing a Wiki could contributing authors perhaps be instructed to use MathML tags, they are slightly more cumbersome than LaTeX commands but surely a Wiki could easily support MathML.

A Big Bad Mother of a FOAM Manual can be put together from the Wiki by whoever wants to sell the thing. There may even be tools that convert MathML content pages to LaTeX, so even editing a book for later retail might not be such an onerous chore, that is if there's ever a market for printed hard copies.

gschaider May 25, 2005 10:59

Hi B.M. Concerning the type
 
Hi B.M.

Concerning the typesetting of formulas: the installed Wiki supports formulas entered in the LaTeX-Syntax. These formulas are converted to MathML or PNG for viewing (depends on the User settings). That was one of the main reasons why I chose this Wiki-implementation. (Examples can be seen in the Testing-Pages)


All times are GMT -4. The time now is 12:25.