[vtk-developers] Documentation Rules

Will Schroeder will.schroeder at kitware.com
Wed Dec 9 06:44:45 EST 2009


I would say publishing in the VTK Journal does not preclude publishing in
another journal with a thoughtful strategy. I would conceptually segregate
the article into several parts: some suitable for academic journals meaning
more math and fancy words :-), and the other parts about implementation,
engineering and reproducibility (data and source code). Of course these
submissions could easily cross-reference each other, etc. I think that for
the algorithmic work that we do this strategy will work  pretty well, with
the benefit that we will be practicing open-science, and not simply trying
to impress other researchers. In the long run I'd love to see the VTK
Journal and other open access journals such as PLoS become the mainstream
journals so it becomes a moot point. The medical folks here at Kitware have
had some luck using the Insight Journal to host conference proceedings
(e.g., the MICCAI journal issues), hopefully we can make similar inroads
into the visualization community.

Of course the strategy may change depending on the IP situation. Luis you've
been doing this longer than most of us, do you have any additional thoughts
on this?

Will

On Tue, Dec 8, 2009 at 11:28 PM, Moreland, Kenneth <kmorel at sandia.gov>wrote:

>  So this brings up a similar question.  Does publishing in the VTK journal
> preclude the document from being submitted/published in another journal?
>
> -Ken
>
>
>
> On 12/8/09 9:57 AM, "Pebay, Philippe P" <pppebay at sandia.gov> wrote:
>
> All right, then I will probably propose an article on the statistics
> classes for there is much to be documented there. Because of space
> requirements we have not explained everything in the new VTK book.
>
> Thanks
> P
> --
> Philippe Pébay
> Sandia National Laboratories
>
> ________________________________________
> From: Will Schroeder [will.schroeder at kitware.com]
> Sent: Tuesday, December 08, 2009 8:53 AM
> To: Pebay, Philippe P
> Cc: David Doria; Andrew Maclean; VTK Developers; Julien Jomier; Luis Ibanez
> Subject: Re: [vtk-developers] Documentation Rules
>
> Yes
>
> On Tue, Dec 8, 2009 at 11:49 AM, Pebay, Philippe P <
> pppebay at sandia.gov<mailto:pppebay at sandia.gov>> wrote:
> So, if I understand well, the VTK journal could also be used for
> documentation purposes and not only for the sake of presenting R&D articles?
>
> P
> --
> Philippe Pébay
> Sandia National Laboratories
>
> ________________________________________
> From: Will Schroeder [will.schroeder at kitware.com<mailto:will.schroeder@
> kitware.com>]
> Sent: Tuesday, December 08, 2009 4:39 AM
> To: David Doria
> Cc: Andrew Maclean; Pebay, Philippe P; VTK Developers; Julien Jomier; Luis
> Ibanez
> Subject: Re: [vtk-developers] Documentation Rules
>
> A couple of notes here that might be helpful to the discussion:
>
> + You may want to refer to the ITK Style Guide for further ideas
> http://www.vtk.org/Wiki/images/c/c6/ITKStyle.pdf (not sure if this is
> the most up to date, hence Luis is CCd). There are other ITK resources
> describing style that might be useful, we can point these out if you
> are interested. Keeping these systems reasonable style-consistent
> would be helpful.
>
> + Recently the VTK ARB (architecture review board) formed (more
> information coming soon see also
> http://www.vtk.org/Wiki/VTK/Architecture_Review_Board) and we have had
> a couple of meetings and actually started getting things done. One
> decision is that we are going to set up a VTK Journal (similar to the
> Insight Journal except it will not serve as a contribution
> gateway/bottleneck to VTK). Julien is working on setting that up now.
> The current thinking is VTK Journal issues created every year, running
> a year in length. (David we noticed that you are contributing new VTK
> classes into the Insight Journal, we'd like to move them as the first
> ever contributions to the VTK Journal starting in the 2010 issue. Let
> me know if you have an issue with that.)
>
> Will
>
>
> On Tue, Dec 8, 2009 at 12:27 AM, Andrew Maclean
> <andrew.amaclean at gmail.com<mailto:andrew.amaclean at gmail.com>> wrote:
> > Hi David,
> > Please also look at: http://www.cmake.org/Wiki/VTK_Coding_Standards.
> > Maybe instead of creating a new page this could be expanded,
> > incorporating the documentation rules. Personally I prefer the term
> > "standards" and not "rules".
> >
> > With respect to Philippe's comments below. I agree that we need some
> > way of handling outside documentation. Referencing here could be to
> > web links and also to bibliographic entries, I think both are
> > acceptable. However,  I think the LaTex source files (and a PDF)
> > should go into the VTK Journal.
> >
> > Regards
> >   Andrew
> >
> > On Tue, Dec 8, 2009 at 1:15 PM, Pebay, Philippe P <
> pppebay at sandia.gov<mailto:pppebay at sandia.gov>> wrote:
> >> David
> >>
> >> Thank you for initiating this effort. A related question is that of
> outside of source documentation: I have been wondering for a while as to
> what is the best way to reference outside documentation inside the code.
> Should this take the form of web links (which tend to become obsolete) to
> wiki pages? Or actual bibliographic entries, when available? I have used the
> latter approach, but it is not perfect by a long shot: for example, some
> references might be available to journal subscribers. Or, the document can
> be large and referring to it as a whole might not be particularly helpful,
> where a more pointed way of referencing would be more readily usable.
> >> Another option would be the incorporation of LaTeX source files, which
> would be compiled in addition to the Doxygen pages.
> >>
> >> Thoughts?
> >>
> >> Thank you
> >> Philippe
> >> --
> >> Philippe Pébay
> >> Sandia National Laboratories
> >>
> >> ________________________________________
> >> From: vtk-developers-bounces at vtk.org<mailto:vtk-developers-bounces@
> vtk.org> [vtk-developers-bounces at vtk.org<mailto:vtk-developers-bounces@
> vtk.org>] On Behalf Of David Doria [
> daviddoria+vtk at gmail.com<mailto:daviddoria%2Bvtk at gmail.com>]
> >> Sent: Monday, December 07, 2009 6:08 PM
> >> To: VTK Developers
> >> Subject: [vtk-developers] Documentation Rules
> >>
> >> Folks,
> >>
> >> I have started compiling a list of what the documentation should look
> like:
> >> http://www.vtk.org/Wiki/Documentation_Rules
> >>
> >> Clearly I have no covered all of the cases - more will come as I
> >> discover more typical cases. Suggestions for things to add are
> >> welcome.
> >>
> >> Agreement on these rules will not only help direct my efforts, but
> >> also ensure that future code will adhere to these guidelines.
> >>
> >> Once we establish the rules, is there a way to have KWStyle type
> >> checks for "documentation correctness"? Something to the effect of
> >> rejecting the commit or turning the dashboard red if the
> >> documentation/comments do not meet the new standards? I think
> >> requiring this is the only way to maintain good documentations -
> >> developers seem to get in a hurry and the first thing that disappears
> >> is the documentation - requiring it would alleviate this problem.
> >>
> >> Thoughts?
> >>
> >> Thanks,
> >>
> >> David
> >> _______________________________________________
> >> Powered by www.kitware.com<http://www.kitware.com>
> >>
> >> Visit other Kitware open-source projects at
> http://www.kitware.com/opensource/opensource.html
> >>
> >> Follow this link to subscribe/unsubscribe:
> >> http://www.vtk.org/mailman/listinfo/vtk-developers
> >>
> >>
> >>
> >> _______________________________________________
> >> Powered by www.kitware.com<http://www.kitware.com>
> >>
> >> Visit other Kitware open-source projects at
> http://www.kitware.com/opensource/opensource.html
> >>
> >> Follow this link to subscribe/unsubscribe:
> >> http://www.vtk.org/mailman/listinfo/vtk-developers
> >>
> >>
> >
> >
> >
> > --
> > ___________________________________________
> > Andrew J. P. Maclean
> > Centre for Autonomous Systems
> > The Rose Street Building J04
> > The University of Sydney  2006  NSW
> > AUSTRALIA
> > Ph: +61 2 9351 3283
> > Fax: +61 2 9351 7474
> > URL: http://www.acfr.usyd.edu.au/
> > ___________________________________________
> > _______________________________________________
> > Powered by www.kitware.com<http://www.kitware.com>
> >
> > Visit other Kitware open-source projects at
> http://www.kitware.com/opensource/opensource.html
> >
> > Follow this link to subscribe/unsubscribe:
> > http://www.vtk.org/mailman/listinfo/vtk-developers
> >
> >
>
>
>
> --
> William J. Schroeder, PhD
> Kitware, Inc.
> 28 Corporate Drive
> Clifton Park, NY 12065
> will.schroeder at kitware.com<mailto:will.schroeder at kitware.com>
> http://www.kitware.com
> (518) 881-4902
>
>
>
>
>
> --
> William J. Schroeder, PhD
> Kitware, Inc.
> 28 Corporate Drive
> Clifton Park, NY 12065
> will.schroeder at kitware.com<mailto:will.schroeder at kitware.com>
> http://www.kitware.com
> (518) 881-4902
>
> _______________________________________________
> Powered by www.kitware.com
>
> Visit other Kitware open-source projects at
> http://www.kitware.com/opensource/opensource.html
>
> Follow this link to subscribe/unsubscribe:
> http://www.vtk.org/mailman/listinfo/vtk-developers
>
>
>
>
>
>    ****      Kenneth Moreland
>     ***      Sandia National Laboratories
> ***********
> *** *** ***  email: kmorel at sandia.gov
> **  ***  **  phone: (505) 844-8919
>     ***      web:   http://www.cs.unm.edu/~kmorel<http://www.cs.unm.edu/%7Ekmorel>
>
>


-- 
William J. Schroeder, PhD
Kitware, Inc.
28 Corporate Drive
Clifton Park, NY 12065
will.schroeder at kitware.com
http://www.kitware.com
(518) 881-4902
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://public.kitware.com/pipermail/vtk-developers/attachments/20091209/9d7b86e5/attachment.html>


More information about the vtk-developers mailing list