[vtk-developers] Documentation Rules

[Will Schroeder]

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]
>> 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