[vtk-developers] Documentation Rules

[David Doria]

On Tue, Dec 8, 2009 at 7:39 AM, Will Schroeder
<will.schroeder at kitware.com> wrote:
> 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/

> William J. Schroeder, PhD

Thanks for the discussion! I have several comments -

+ I moved the content to the Coding Standards page. It fits well
there. According to wiki rules pages can never be deleted - so do we
just remove the link to the Documentation_Rules and it will just be a
"wiki page memory leak", or is there a way to delete it? I'm going to
proceed adding comments of the types that I have defined so far, any
objections?

+ I typically wrap c++ code snippets in <source lang="cpp">, but on
the existing Coding Standards the snippets do not seem to be wrapped
in anything but they appear with a nice box around them - which style
is preferred? While we're at it, we should add a "Wiki Standards"
section detailing things like this as well as things we've discussed
before but not come to a solid conclusion about such as the
VTK_Page_Name naming convention (which I forgot in the
Documentation_Rules case, sorry Bill!).

+ I realize the wiki is shared, but it seems confusing to allow links like this:
http://www.cmake.org/Wiki/VTK_Coding_Standards

when this is more coherent:
http://www.vtk.org/Wiki/VTK_Coding_Standards

thoughts on this?

+ VTK Journal - I think this is a GREAT idea. My submissions always
felt out of place on the IJ. With a toolkit this big, I think this is
really necessary for people to share their related work. Will - Julien
has been working with me to perform this switch, I have no issues with
it, in fact, I'm glad to see it! I don't understand the concept of an
"issue" of a digital journal though - isn't it just a rolling thing
that you can see any entries that have been submitted from the time
the journal started until the present?

Thanks,

David