Generating ontological documentation for Elixir?

[Rich Morin]

The organization of the Elixir documentation reflects the structure of
the code base. So, for example, all of the functions in the Enum module
are lumped together. There are two problems with this:

* Related functions from other modules (e.g., List, Stream) are not shown.

* Cross-module categories of functions (e.g., Filter, Inspect) are not indexed.

It should be possible to generate ontological documentation, using a
combination of crowd-sourcing and appropriate tooling. This could let
users (for example) skim a list of categories, looking for potentially
relevant functions.

See this page for a naive example and further discussion:

OntoDoc
http://wiki.cfcl.com/Projects/Elixir/OD/WebHome

Comments and suggestions welcome...

-r
--
http://www.cfcl.com/rdm Rich Morin r...@cfcl.com
http://www.cfcl.com/rdm/resume San Bruno, CA, USA +1 650-873-7841

Software system design, development, and documentation

[Alexei Sholik]

I like the idea. However, I don't see how it should be generated.

You have created a number of categories and assigned functions from Enum to them. That seems like a good way to go and can be done for the whole core library. In which way are you suggesting to generate it?

--
You received this message because you are subscribed to the Google Groups "elixir-lang-talk" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-ta...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-talk/4A931C12-416E-4C5F-AC68-968A84CDAC17%40cfcl.com.
For more options, visit https://groups.google.com/d/optout.

[eksperimental]

This is such a great idea Rich,
I think it opens the door to let people create really cool stuff
while integrating the docs with other tools, not only from the
generated documentation..

[Rich Morin]

On Sep 11, 2015, at 04:47, Alexei Sholik <alcos...@gmail.com> wrote:
> I like the idea. However, I don't see how it should be generated.
>
> You have created a number of categories and assigned functions from
> Enum to them. That seems like a good way to go and can be done for the
> whole core library. In which way are you suggesting to generate it?

I'm open to suggestions for the specifics, but the general idea is that
any Elixero should be allowed (nay, encouraged!) to participate. This
may result in some noise (eg, overlapping categories, iffy links), but
I'm willing to live with this in trade for the useful information.

As my web page indicates, modules could contain attributes such as

@ontodoc Transform Traverse

Once we have an initial set of categories and the attribute definitions
are hammered out, anyone could suggest attributes using a pull request.
The attributes could then be harvested mechanically, turned into summary
files, and merged with other (hand-edited and/or harvested) files.

On Sep 11, 2015, at 05:09, eksperimental <eksper...@autistici.org> wrote:
> This is such a great idea Rich. I think it opens the door to let people

> create really cool stuff while integrating the docs with other tools,
> not only from the generated documentation.

Indeed. For example, we could set up a Phoenix app with index pages, a
cool GUI (eg, D3) navigation, etc. I'd suggest using a graph database
(eg, Neo4j) on the back end, to support arbitrary queries, but this is
an implementation detail.

Hmmmm. Would anyone else be up for a documentation BOF at ElixirConf?

[Ben Wilson]

As just a point of clarification, can you elaborate on the naming? I'm a bit fuzzy on the relationship between ontology and the manner in which these docs are organized.

[Rich Morin]

On Sep 11, 2015, at 07:45, Ben Wilson <benwil...@gmail.com> wrote:
> As just a point of clarification, can you elaborate on the naming?
> I'm a bit fuzzy on the relationship between ontology and the manner
> in which these docs are organized.

This definition is a reasonable starting point:

In computer science and information science, an ontology is a formal
naming and definition of the types, properties, and interrelationships
of the entities that really or fundamentally exist for a particular
domain of discourse. ...

-- https://en.wikipedia.org/wiki/Ontology_(information_science)

So, an ontology is a set of categories and relationships (ie, a graph).
It is typically organized as a hierarchy, with "Thing" at the top. The
tree may include duplication of categories and/or entities:

Thing
Inspect
all?, any?, count, ...
...
Traverse
all?, any?, chunk_by, ...

My example has half a dozen categories and not much structure. I'd
expect the full project to increase both substantially. FWIW, the
categories and relationships can be quite arbitrary. For example,
we might want a relationship of "see also" between categories.

FYI, ontologies are often described as lattices, going from Thing to
Nothing. (The Thing category includes everything; Nothing includes
nothing :-). However, I find it more useful to think of them as DAGs.