[vtk-developers] Documentation Rules

Tue Dec 8 11:53:31 EST 2009

Yes

On Tue, Dec 8, 2009 at 11:49 AM, Pebay, Philippe P <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]
> 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> 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>
> 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 [vtk-developers-bounces at vtk.org]
> On Behalf Of David Doria [daviddoria+vtk at gmail.com<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
> >>
> >> 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
> >>
> >> 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
> >
> > 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
> 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
http://www.kitware.com
(518) 881-4902
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://public.kitware.com/pipermail/vtk-developers/attachments/20091208/1f3681f1/attachment.html>