CFD Online Discussion Forums

CFD Online Discussion Forums (http://www.cfd-online.com/Forums/)
-   OpenFOAM Installation (http://www.cfd-online.com/Forums/openfoam-installation/)
-   -   [Discussion] Restructuring the Installation page at openfoamwiki.net (http://www.cfd-online.com/Forums/openfoam-installation/102534-discussion-restructuring-installation-page-openfoamwiki-net.html)

wyldckat May 27, 2012 10:57

[Discussion] Restructuring the Installation page at openfoamwiki.net
 
Greetings to all!

I'm starting this thread to discuss the restructuring of this page: http://openfoamwiki.net/index.php/Installation
I know that the wiki page has a discussion page of its own at the wiki, but that's barely read/answered by anyone ;)

And I'm honestly becoming very tired of constantly answering almost the same things over and over and over and over.... and not matter how many blog posts I can write, how many answers I write, they'll only postpone what needs to be done: we must restructure the Installation page at the openfoamwiki.net :D

So, to start off (instead of creating havoc and chaos on my own) here is the proposed structure:
  1. Installation page:
    • Introduction - chapter (or is it section?) where it's explained how the content is distributed. And focus that officially only Linux is supported and that variants/forks aren't officially supported/endorsed.
    • Linux - a chapter explaining that these instructions could/should work with POSIX compatible Operating Systems (BSD, HP-UN*X, etc...). Then shows a list sub-pages or a sub-category tree for Linux installations.
    • Mac OS X - a chapter explaining that this is very similar to POSIX, but not quite the same... or something like that. Perhaps also focus on the details that need to be kept in mind: must use a case sensitive mount and so on. Then shows a list sub-pages or a sub-category tree for Mac OS X installations.
    • Windows - a chapter briefly explaining the situation... and then shows a list sub-pages or a sub-category tree for Windows installations.
  2. Category: Installing OpenFOAM on Linux
    1. Category: OpenFOAM 2.1.x
    2. Category: OpenFOAM 1.6-ext
    3. ...
  3. Category: Installing OpenFOAM on Mac OX
    1. Category: OpenFOAM 2.1.x
    2. Category: OpenFOAM 1.6-ext
    3. ...
  4. Category: Installing OpenFOAM on Windows
    1. Category: OpenFOAM 2.1.x
    2. Category: OpenFOAM 1.6-ext
    3. ...
The advantage of using categories is the possibility to use the automatic tree system shown here: http://openfoamwiki.net/index.php/TestWyldckat - uses this wiki code:
Code:

{{#categorytree:OpenFOAM guide|mode=pages}}
Although categories are used, the pages would then be placed like this:
  • Installation
  • Installation/Linux
  • Installation/Mac OS X
  • Installation/Windows
  • Installation/Linux/OpenFOAM 2.1.x
  • Installation/Linux/OpenFOAM 1.6-ext
  • ...

Copy-paste-modify instructions is pretty easy, so to me it makes sense to have a page per version/variant.

As for Linux distributions, since some details change considerably (e.g. Fedora et al use "module load"), there are two possibilities that should be considered/discussed:
  • Use the "hide" feature that AFAIK openfoamwiki.net doesn't have yet, but where specific instructions for each distribution+version (e.g. Fedora 16) would be visible only upon clocking the link "show/hide".
  • Or use the category system:
    • Category: Installing OpenFOAM on Linux
      • Category: Installing OpenFOAM on Fedora
        • e.g. Category: OpenFOAM 2.1.x


So here it is, the idea I've brewed so far. If this is already in discussion elsewhere... I'm not familiar with it :(


I think there are some details here that escape me, such as "OpenFOAM 2.1.x" being a sub-category of "OpenFOAM on Linux", but I think that this might be overcome by the page title itself. For example, the category tree would look like this:
  • Installing OpenFOAM on Linux
    • Installation/Linux/OpenFOAM 2.1.x
    • Installation/Linux/OpenFOAM 1.6-ext
    • Installing OpenFOAM on Fedora
      • Installation/Linux/Fedora/OpenFOAM 2.1.x

edit: In case of situations such as Debian and Ubuntu behaving almost identically, a page could be tagged with both categories: "Installing OpenFOAM on Debian" and "Installing OpenFOAM on Ubuntu", for the same page "Installation/Linux/Debian/OpenFOAM 2.1.x".

Best regards,
Bruno

gschaider May 28, 2012 11:15

Quote:

Originally Posted by wyldckat (Post 363325)
Greetings to all!

I'm starting this thread to discuss the restructuring of this page: http://openfoamwiki.net/index.php/Installation
I know that the wiki page has a discussion page of its own at the wiki, but that's barely read/answered by anyone ;)

And I'm honestly becoming very tired of constantly answering almost the same things over and over and over and over....

Much appreciated

Quote:

Originally Posted by wyldckat (Post 363325)
and not matter how many blog posts I can write, how many answers I write, they'll only postpone what needs to be done: we must restructure the Installation page at the openfoamwiki.net :D

Agreed

Quote:

Originally Posted by wyldckat (Post 363325)
So, to start off (instead of creating havoc and chaos on my own) here is the proposed structure:
  1. Installation page:
    • Introduction - chapter (or is it section?) where it's explained how the content is distributed. And focus that officially only Linux is supported and that variants/forks aren't officially supported/endorsed.
    • Linux - a chapter explaining that these instructions could/should work with POSIX compatible Operating Systems (BSD, HP-UN*X, etc...). Then shows a list sub-pages or a sub-category tree for Linux installations.
    • Mac OS X - a chapter explaining that this is very similar to POSIX, but not quite the same... or something like that. Perhaps also focus on the details that need to be kept in mind: must use a case sensitive mount and so on. Then shows a list sub-pages or a sub-category tree for Mac OS X installations.
    • Windows - a chapter briefly explaining the situation... and then shows a list sub-pages or a sub-category tree for Windows installations.
  2. Category: Installing OpenFOAM on Linux
    1. Category: OpenFOAM 2.1.x
    2. Category: OpenFOAM 1.6-ext
    3. ...
  3. Category: Installing OpenFOAM on Mac OX
    1. Category: OpenFOAM 2.1.x
    2. Category: OpenFOAM 1.6-ext
    3. ...
  4. Category: Installing OpenFOAM on Windows
    1. Category: OpenFOAM 2.1.x
    2. Category: OpenFOAM 1.6-ext
    3. ...
The advantage of using categories is the possibility to use the automatic tree system shown here: http://openfoamwiki.net/index.php/TestWyldckat - uses this wiki code:
Code:

{{#categorytree:OpenFOAM guide|mode=pages}}
Although categories are used, the pages would then be placed like this:
  • Installation
  • Installation/Linux
  • Installation/Mac OS X
  • Installation/Windows
  • Installation/Linux/OpenFOAM 2.1.x
  • Installation/Linux/OpenFOAM 1.6-ext
  • ...

Copy-paste-modify instructions is pretty easy, so to me it makes sense to have a page per version/variant.

As for Linux distributions, since some details change considerably (e.g. Fedora et al use "module load"), there are two possibilities that should be considered/discussed:
  • Use the "hide" feature that AFAIK openfoamwiki.net doesn't have yet, but where specific instructions for each distribution+version (e.g. Fedora 16) would be visible only upon clocking the link "show/hide".
  • Or use the category system:
    • Category: Installing OpenFOAM on Linux
      • Category: Installing OpenFOAM on Fedora
        • e.g. Category: OpenFOAM 2.1.x


So here it is, the idea I've brewed so far. If this is already in discussion elsewhere... I'm not familiar with it :(


I think there are some details here that escape me, such as "OpenFOAM 2.1.x" being a sub-category of "OpenFOAM on Linux", but I think that this might be overcome by the page title itself. For example, the category tree would look like this:
  • Installing OpenFOAM on Linux
    • Installation/Linux/OpenFOAM 2.1.x
    • Installation/Linux/OpenFOAM 1.6-ext
    • Installing OpenFOAM on Fedora
      • Installation/Linux/Fedora/OpenFOAM 2.1.x

edit: In case of situations such as Debian and Ubuntu behaving almost identically, a page could be tagged with both categories: "Installing OpenFOAM on Debian" and "Installing OpenFOAM on Ubuntu", for the same page "Installation/Linux/Debian/OpenFOAM 2.1.x".

Best regards,
Bruno

Sounds like a plan. What I'd propose would be the following:
  1. Copy/paste the content of the current page to somthing called Installation/OldMonolithicVersion (I'm not sure, but I think in this case renaming/moving would mean trouble)
  2. On top of the old page add a remark to the effect "This page currently under construction. Have a look at OldMonolithicVersion"
  3. Start hacking away
Also I'd propose to mark sub-pages for OS where on knowledge is available with a remark "Maintainer wanted"

Bernhard

akidess May 29, 2012 07:13

Thanks for your initiative Bruno. This is really overdue, there's lots of installation related text on the wiki that is hopelessly outdated, making it hard to find the actual information.

About the category tree, organizing according to OpenFoam versions (as follows) seems more natural to me than the tree you suggested, but I think that's subjective.

- Anton

Quote:

Originally Posted by wyldckat (Post 363325)
For example, the category tree would look like this:
  • Installing OpenFOAM on Linux
    • Installation/Linux/OpenFOAM 2.1.x
      • Installation/Linux/Fedora/OpenFOAM 2.1.x
    • Installation/Linux/OpenFOAM 1.6-ext


wyldckat May 29, 2012 15:36

Hi Bernhard and Anton,

@Bernhard: OK, as soon as I can, perhaps next weekend, I'll start hacking away through the pages :D

@Anton:
Quote:

Originally Posted by akidess (Post 363556)
About the category tree, organizing according to OpenFoam versions (as follows) seems more natural to me than the tree you suggested, but I think that's subjective.

:eek: I'm not certain how to do that structure with categories... It'll take some experimentation...

[RANT]
After the conclusions that were inevitably reached with the Nucleation project, the only logical thing right now is to do documentation in the fully open wiki, instead of overblown scripting :D - although it was a good exercise :rolleyes: - so this way people can learn and experience more about the shell, instead of hogging all of the experience to ourselves :cool:
[/RANT]

Keep ideas coming!

Best regards,
Bruno

akidess May 30, 2012 03:00

Quote:

Originally Posted by wyldckat (Post 363653)
@Anton:
:eek: I'm not certain how to do that structure with categories... It'll take some experimentation...


Does this look better? (I switched 2.1.x and Fedora)
Quote:

  • Installing OpenFOAM on Linux
    • Installation/Linux/OpenFOAM 2.1.x
      • Installation/Linux/OpenFOAM 2.1.x/Fedora
    • Installation/Linux/OpenFOAM 1.6-ext


shreyasr August 1, 2012 16:54

Quote:

Originally Posted by akidess (Post 363556)
Thanks for your initiative Bruno. This is really overdue, there's lots of installation related text on the wiki that is hopelessly outdated, making it hard to find the actual information.

About the category tree, organizing according to OpenFoam versions (as follows) seems more natural to me than the tree you suggested, but I think that's subjective.

- Anton

I'm more at home with the above kind of categorisation. Under each version of OpenFOAM, there could a page with specific instructions for each Operating System like Fedora, SUSE, Ubuntu etc.

gschaider August 6, 2012 18:33

Quote:

Originally Posted by shreyasr (Post 374919)
I'm more at home with the above kind of categorisation. Under each version of OpenFOAM, there could a page with specific instructions for each Operating System like Fedora, SUSE, Ubuntu etc.

For practical reasons I'm more in favour of having more general instructions and describing the differences. Because otherwise certain pages might become hopelessly out of date if no one with that specific distro bothers to update them

wyldckat August 7, 2012 06:01

Quote:

Originally Posted by gschaider (Post 375676)
For practical reasons I'm more in favour of having more general instructions and describing the differences. Because otherwise certain pages might become hopelessly out of date if no one with that specific distro bothers to update them

The problem is if there are several differences... but duly noted :)

wyldckat August 11, 2012 17:48

FYI: I've began the restructuring process.
For now, I'm doing stuff sort-of in the back-doors and not editing the main Installation page.
The current entry point is this: http://openfoamwiki.net/index.php/Installation/Linux

For now, it seems that we can get 2 types of category tree listings in the same tree (and maybe also possible in separate trees):
  • Per Linux Distribution.
  • And per OpenFOAM version/variant.
I'm still writing the first pages, so this is still subject to evolution pains ;)
I've got the idea that the generic source code installation instructions can be written using templates, which would make it easier to write and maintain a lot of stuff... but it's still too early to decide :)

wyldckat August 12, 2012 17:57

OK, I think the base structure is all laid out: http://openfoamwiki.net/index.php/Installation

The old monolithic page has been copy-pasted and referred to at the top of the page.

The category tree seems rather clumsy right now, but the only using sub-categories in the tree lacks detail, while the sub-pages prefix listing mode is hard-coded to 3 columns...
oh well, optimum is the enemy of good :D

Next weekend(s) I hope to do the following:
  • Finish writing the page http://openfoamwiki.net/index.php/In...OpenFOAM-2.1.1
  • Take care of moving and revamping the cross-compilation pages for Windows.
  • Move the instructions for Mac OS, if no one else does it before I do ;)
  • Start adding more versions and copy some of the stuff I already have in my blog here...

wyldckat May 5, 2013 12:44

Greetings to all!

:eek: It's been a while since I gave some feedback on this.

The last few days I've been in a bit of a vacation and I managed to focus on taking care of some of the things I wanted to do. This included updating and adding installation instructions, including:
Just for reference, the following pages are still mid-way (started to write them, but haven't finished them yet):
And from the previous post, the following are still waiting as well:

Quote:

Originally Posted by wyldckat (Post 376703)
  • Take care of moving and revamping the cross-compilation pages for Windows.
  • Move the instructions for Mac OS, if no one else does it before I do ;)

Best regards,
Bruno

wyldckat October 26, 2013 11:17

Greetings to all!

I was going to open two discussion threads at openfoamwiki.net regarding this, but I think this is a better place for this. The questions are somewhat simple/short:
  1. I followed AntonChupin's idea and did some category association to the "Howto" pages listed here: http://openfoamwiki.net/index.php/In...d_Instructions
  2. I wrote some time ago the wiki pages available here: https://sourceforge.net/u/wyldckat/helyxos/wiki/Home/ - the objective back then was for them to be easily copy-pasted into HelyxOS' own wiki. But since they preferred to keep things separate, I was wondering if it would be a good idea to start the installation sub-page for HelyxOS at http://openfoamwiki.net/index.php/Installation/HelyxOS

In review of the previous post, I'm now keeping track of the pages that I still need to finish writing here: http://openfoamwiki.net/index.php/Us...finish_writing

Best regards,
Bruno

gschaider October 28, 2013 19:14

Quote:

Originally Posted by wyldckat (Post 459142)
Greetings to all!

I was going to open two discussion threads at openfoamwiki.net regarding this, but I think this is a better place for this. The questions are somewhat simple/short:
  1. I followed AntonChupin's idea and did some category association to the "Howto" pages listed here: http://openfoamwiki.net/index.php/In...d_Instructions

  1. You mean as Installation/Outdated/XX or as Installation/XX ? Both have their merits. The first is clearer. The second leads to less redirect when pages become obsolete

    Quote:

    Originally Posted by wyldckat (Post 459142)
  2. I wrote some time ago the wiki pages available here: https://sourceforge.net/u/wyldckat/helyxos/wiki/Home/ - the objective back then was for them to be easily copy-pasted into HelyxOS' own wiki. But since they preferred to keep things separate, I was wondering if it would be a good idea to start the installation sub-page for HelyxOS at http://openfoamwiki.net/index.php/Installation/HelyxOS

  3. OK. At first I was tempted to have Installation/ThirdParty/HelyxOS (or similar) but that would be the sin of overstructuring of which I was guilty in the past (if you know the old, old front-page of the Wiki you know what I mean)
    Quote:

    Originally Posted by wyldckat (Post 459142)

Quote:

Originally Posted by wyldckat (Post 459142)
In review of the previous post, I'm now keeping track of the pages that I still need to finish writing here: http://openfoamwiki.net/index.php/Us...finish_writing

Oh . teaser-trailers . ;)

wyldckat October 29, 2013 18:57

Hi Bernhard,

Many thanks! Then so it shall be:
  • Installation/Outdated/XX for the very old instructions.
  • Installation/HelyxOS for community installation/building instructions for HelyxOS
  • Installation/Discretizer for community installation/building instructions for Discretizer.
And indeed... I'm racking up way too many teaser trailers... I gotta start focusing more on making the movies :D

Best regards,
Bruno

gschaider October 29, 2013 21:23

Quote:

Originally Posted by wyldckat (Post 459729)
And indeed... I'm racking up way too many teaser trailers... I gotta start focusing more on making the movies :D

Seriously. That can become a reason for people not contributing "Oh. The mighty Bruno will write a page about this anyway. Then I don't have to make an attempt. Although right now I have the time and the knowledge"

wyldckat November 1, 2013 19:43

Hi Bernhard,

Many thanks! I've gotten the message loud and clear!

I'm going to look/search into the wiki and find a good way to change from the point of view of "me me me" to "if you don't know what you could write about, here are some ideas"/"these pages are currently incomplete, feel free to help with anything in it".

I know the "HowTo" section already has something like that, but there are other pages (beyond the ones I've started and haven't finished yet :rolleyes:) that still need some help. And there was that new FAQ section on how to help, so I'll have a look into how to sort it all out.

Best regards,
Bruno

wyldckat November 2, 2013 12:43

And here we go, here's what I've taken care of today:
  1. Added an entry to http://openfoamwiki.net/index.php/FAQ/Wiki on where people can find incomplete pages and ideas for new pages.
  2. Created a category for incomplete pages and populated it: http://openfoamwiki.net/index.php/Ca...complete_pages
  3. The page with ideas for new pages is here: http://openfoamwiki.net/index.php/FAQ/Wiki/Ideas - And check the talk page ;)
  4. I've trimmed down my TO-DO list down to 3 pages: http://openfoamwiki.net/index.php/Us...finish_writing
  5. And did the following additions/modifications to the subpages at http://openfoamwiki.net/index.php/Installation
    1. Moved a few pages that were on the HowTo section to this section: http://openfoamwiki.net/index.php/In...#Other_Details
    2. Outdated pages regarding compilation/installation of OpenFOAM on Linux were moved to this section (as stipulated in the previous posts): http://openfoamwiki.net/index.php/In...d_Instructions
    3. I finally made the move/renaming of the pages for Mac OS X and Windows:
      1. http://openfoamwiki.net/index.php/Installation/Mac_OS
      2. http://openfoamwiki.net/index.php/Installation/Windows
    4. Added the pages for Discretizer and Helyx-OS: http://openfoamwiki.net/index.php/In...Party_software
  6. And removed the stale links for the tips and how-to pages that have been moved to the locations above.
It took me roughly 6h to do all of this... Now to gather up some more inspiration to finish those 3 incomplete pages of mine :rolleyes:

Best regards,
Bruno

edit: I didn't manage to gather the inspiration to finish writing the 3 pages. I'll try to have a look into them in a few weekends from now.


All times are GMT -4. The time now is 15:35.