[vtk-developers] Static pages for VTKExamples

[Bill Lorensen]

Andras,

The current VTK Examples have been hosted on a mediawiki site for 6 or 7 years.

The new approach is to use either github or gitlab. The new
VTKExamples (which is still experimental) is a gitlab wiki so
versioning is not an issue. I don't believe it is searched bu google.

The second approach uses github pages to host a static wiki. The look
and feel of the github pages is much better than that of the gitlab
wiki. It also renders large pages much faster.

https://gitlab.kitware.com/lorensen/VTKExamples/wikis/home
versus
https://lorensen.github.io/VTKExamples/site

BTW, both sites are generated automatically from the source code tree.
Addition documentation of examples is written in markdown.


Bill


On Mon, May 15, 2017 at 2:09 PM, Andras Lasso <lasso at queensu.ca> wrote:
> Google indexing dynamic pages should not be an issue (most websites are dynamic), it may just require some tuning.
>
> However, there are a couple of other potential issues with using the wiki for hosting examples.
>
> Versioning may be a one of the most difficult problem to solve. We use MediaWiki to maintain Slicer documentation and we've found that maintaining up-to-date documentation for multiple versions is unsustainable (you have to create a large number of wiki pages for each software version), creates confusion (as Google keeps directing users to pages belonging to random software versions), and limits access (you cannot distribute documentation as a package that can be used offline). Hosting documentation on a github or other documentation-oriented service (such as readthedocs) does not have these issues.
>
> Another problem hosting on the wiki (again, learned lessons from Slicer) that mixing user-written content with automatically-generated content discourages users from contributing, as it becomes unclear which page is generated manually/automatically, how pages can be modified when they are automatically generated. Also number and size of automatically generated pages (especially when pages are generated for each software version) can be very big. Maintaining history for automatically generated pages is not necessary and if it cannot be avoided then it could be an additional burden on the wiki.
>
> Searching on the wiki seems to be quite limited on the wiki (at least as it is set up now). For example, searching for Subdivision has 3 hits on the github version and none on the wiki.
>
> Andras
>
>
> -----Original Message-----
> From: vtk-developers [mailto:vtk-developers-bounces at vtk.org] On Behalf Of Bill Lorensen
> Sent: Monday, May 15, 2017 12:10 PM
> To: Will <will.schroeder at kitware.com>
> Cc: VTK Developers <vtk-developers at vtk.org>; Andrew Maclean <andrew.amaclean at gmail.com>
> Subject: Re: [vtk-developers] Static pages for VTKExamples
>
> I think I fixed the link issues.
>
>
> On Mon, May 15, 2017 at 7:43 AM, Bill Lorensen <bill.lorensen at gmail.com> wrote:
>> Will
>>
>> I'm still working out the kinks. Before I  go too much further, I
>> want to get feedback on which of the two approaches is better.
>>
>> I will look at those missing links.
>>
>> On May 15, 2017 6:35 AM, "Will Schroeder" <will.schroeder at kitware.com>
>> wrote:
>>>
>>> Bill this is a prototype correct? I ask because if you travel down
>>> the hierarchy Cxx Examples -> Input & Output -> 3D File Formats ->
>>> VTK Formats
>>> -> Input and then click on "ReadUnstructuredGrid" it 404s me.
>>>
>>> On Sun, May 14, 2017 at 3:08 PM, Bill Lorensen
>>> <bill.lorensen at gmail.com>
>>> wrote:
>>>>
>>>> Folks,
>>>>
>>>> Take a look here:
>>>> https://lorensen.github.io/VTKExamples/site
>>>>
>>>> These are static HTML pages that I think google will find. looks
>>>> pretty good on my phone.
>>>>
>>>> Also, the style is much cleaner than:
>>>> https://gitlab.kitware.com/lorensen/VTKExamples/wikis/home
>>>>
>>>> Bill
>>>> _______________________________________________
>>>> Powered by www.kitware.com
>>>>
>>>> Visit other Kitware open-source projects at
>>>> http://www.kitware.com/opensource/opensource.html
>>>>
>>>> Search the list archives at:
>>>> http://markmail.org/search/?q=vtk-developers
>>>>
>>>> Follow this link to subscribe/unsubscribe:
>>>> http://public.kitware.com/mailman/listinfo/vtk-developers
>>>>
>>>
>>>
>>>
>>> --
>>> William J. Schroeder, PhD
>>> Kitware, Inc. - Building the World's Technical Computing Software
>>> 28 Corporate Drive
>>> Clifton Park, NY 12065
>>> will.schroeder at kitware.com
>>> http://www.kitware.com
>>> (518) 881-4902
>
>
>
> --
> Unpaid intern in BillsBasement at noware dot com _______________________________________________
> Powered by www.kitware.com
>
> Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html
>
> Search the list archives at: http://markmail.org/search/?q=vtk-developers
>
> Follow this link to subscribe/unsubscribe:
> http://public.kitware.com/mailman/listinfo/vtk-developers
>



-- 
Unpaid intern in BillsBasement at noware dot com