[pgrouting-dev] Documentation review comments

[Daniel Kastl]

On Mon, May 27, 2013 at 12:18 AM, Stephen Woodbridge <
woodbri at swoodbridge.com> wrote:

> Hi Daniel,
>
> You are doing an awesome job with the documentation. I have a few minor
> comments on things I have noticed while review it.
>
> * Can we break out the "Utility functions" to a separate page that gets
> indexed to make it easier to find. It is currently at the bottom of the
> pgrouting_analytics page.
>

I didn't look at this much yet, but I thought there should be 1 page for
each function.
Then if these functions should be explained in context, grouped together
however, then I would add a chapter to "Tutorials" for example.

So if there is no single page yet for some functions, then it'S just not
done yet.


>
> * pgr_quote_ident seems to be on its own page, but this and the utilities
> should be cross references may via the "See Also" links.
>

Some "See Also" links were obvious, but I thought it's OK to do this at the
end. Otherwise if a page name changes, we need to fix it again.



>
> * I see references to "(built-in function)" but don't remember seeing any
> description of what this means to the user or why we are calling them out
> as such.
>

I don't remember either ;-)
Where did you find this?



>
> * many of the built-in functions do not conform to our naming convention.
> So may be we need to focus on updating these functions and the functions
> that call these. Also I think the doc is just out of date for many of
> these, because I seem to remember changing the names on these.
>

Could be. I'm usually looking at pgAdmin3 to get a list of all functions.
Some I didn't touch, because I wasn't sure they would be removed or renamed.



>
> * I notice in the index that we have references "module", "[1]", "[2]",
> "[3]", etc. I'm not sure the [n] is very useful and should probably get
> changed to some text string that is more meaningful. And common module, ...
> in index makes no sense to me. I'm not sure how this all works in sphinx or
> if we can clean this up or not.
>

"Module" is a feature that is done by Sphinx auto-magically when it's not
turned off. And a "Module" is defined like here

.. index::
    single: pgr_kdijkstraCost(text,integer,integer[],boolean,boolean)
    single: pgr_kdijkstraPath(text,integer,integer[],boolean,boolean)
    module: kdijkstra

I'm not su re really how useful this is for us. It just does the index
records itself.
And I don't know well how to configure it. We can easily turn it off if
it's just confusing and enable it again when we know out to use it right.

Daniel



>
> Anyway, some ideas to make things a little nicer. I really like how
> professional and consistent the docs look. Great job on these.
>
> Thanks,
>   -Steve
> ______________________________**_________________
> pgrouting-dev mailing list
> pgrouting-dev at lists.osgeo.org
> http://lists.osgeo.org/**mailman/listinfo/pgrouting-dev<http://lists.osgeo.org/mailman/listinfo/pgrouting-dev>
>



-- 
Georepublic UG & Georepublic Japan
eMail: daniel.kastl at georepublic.de
Web: http://georepublic.de
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/pgrouting-dev/attachments/20130527/eb2b608d/attachment.html>