[vtk-developers] Documentation Rules

Tue Dec 8 18:12:25 EST 2009

Excellent this is a good use of the journal.

Andrew

On Wed, Dec 9, 2009 at 3: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 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<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 at vtk.org> [vtk-developers-bounces at vtk.org<mailto:vtk-developers-bounces at 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
>
>

-- 
___________________________________________
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/
___________________________________________