Isn't this just promoting the concept of a well written wiki? Linking documents together IS a graph, whether you store it in a graph db or not. Graph DBs shine when it comes to graph queries, storing documents that are well linked can be handled with any old relational DB
Could you clarify: What are the nodes and edges? May the graph contain cycles? May the graph be infinite? If the graph is infinite, do we need a distinguished initial node? Do non-isomorphic graphs always correspond to different computations, or do you have a coarser notion of equivalence (say, graph homeomorphism)?
I've read papers where the space of possible computations for a given (typically, toy, even loop-free) nondeterministic concurrent program is represented as a directed topological space (see “directed algebraic topology” for more information), but these spaces are more general than directed graphs.
I don't mean directed graphs, only vertices and edges.
I don't think you would need to deal with infinite graphs, as "arbitrarily large" should be able to cover all (finite) possible computations and/or representations.
My guess is that every graph may correspond to an infinite number (though, not necessarily every) of possible computations and/or representations, depending on which "correspondence function" is being used to analyze the graph (though there may be additional "correspondences" between those functions and/or their results).
We'd need to be talking about a concrete example to say with much specificity, but a node is basically a "thing" and an edge is a binary relationship between two things. A thing may have relationships with itself.
The precise "information" associated to them could be "anything", but would be proscribed by the computation and/or representation being disccussed and the graph in question.
How disappointing. I was expecting something more concrete, like “every node is a sequence point and every edge is a possible transition” or “every node is a point at which a nondeterministic event occurs and every edge corresponds to a causal relation between events”. But if you just say “a computation is a graph” and give no further details, then there's no actual benefit to modeling computations as graphs.
I'm even more annoyed by your use of the word “isomorphic”, which, FYI, doesn't mean “vaguely similar in some way I can't articulate”. It only makes sense two speak of two mathematical objects being “isomorphic” when they belong in the same category. What category do you have in mind, that includes both computations and graphs as objects, and what are the morphisms between them?
Disappointing? You are the one coming to me expecting an example-oracle that produces them on demand.
E.g.
Computation / representation:
2 + 2
Graph
[+]
/ \
[2] [2]
There is a way to produce the graph from the computation / representation and vice versa. There is a way to do that for every possible computation / representation and every possible graph (though, not necessarily with every pair).
This could be described as a compiler or compiler-like. There are many interesting things to do with them, but in this example all that is needed to consider is the construction of an Abstract Syntax Tree from a string and an in-order tree walker that emits the contents of the nodes to an output string.
(0) You said “I don't mean directed graphs, only vertices and edges.” But a syntax tree, viewed as a graph, is very much a directed one - the relation between a parent node and its children is asymmetric.
(1) A syntax tree isn't the same thing as a computation. Of course, you can produce computations by interpreting syntax trees, but: (a) It's perfectly possible for two distinct syntax trees to produce the same computation. [Say, by renaming all variables.] (b) It's also perfectly possible that interpreting the same syntax tree twice will produce completely different computations! [Say, if your language isn't pure.] Unsurprisingly, a syntax tree is a representation of syntax, not computation.
(2) Yes, I'm disappointed, because I expected your observation that “every computation (...) is isomorphic[sic] to some graph” to provide more insight than it turned out to.
Placing [sic] into a paraphrasing is just misleading.
0) You asked, "What information is associated to [nodes and edges]?". In this example, one piece of information is the direction of an edge.
1) I don't think I claimed they were the same. In fact, I am claiming that one can be represented by the other and vice versa. a) yes, that is part of the reason I conject that each graph may be associated with an "infinite number" of computations and/or representations b) also a reason -- there are perhaps an infinite number of languages, interpreters, compilers, etc. (some of which may produce the same result) for a given graph.
2) It was only an observation that the comment I responded to claimed only a subset of the truth. Anything done on a computer can be considered as a graph.
Broadly speaking, in graph reduction the nodes are functions and values and the edges are steps in the computation that can be taken to apply functions to those values. After application that node becomes a new value, etc. until the program is evaluated or terminated.
What did you not find useful about my numerous answers?
Basically, everything is in some way equivalent to some graph. Since anything is an example, it's difficult to say much without using an example, which then necessarily constrains the discussion.
It would be more useful if you presented an example computation or representation, then I could show you how to make and reverse an equivalent graph. (Which then might show you what information might be associated with nodes and edges.)
I don't think there's any reason to be judgy about the other commenter. I understand you wanted a rigorous definition but there are better ways to ask for it than making unilateral demands and using negative terms like "disappointing" and "annoying". You may be well versed in these subjects but it is possible to be technically correct and gracious at the same time. I think you're capable of doing so and you would probably find more fruitful discussions by taking that path.
The point isn't necessarily one graph representation, but simply that any problem can be looked at in a graphy manner if you try hard enough, so "hey, it's a graph" isn't an interesting insight. But to answer your question, data flow graphs are a general representation of function composition, and Turing machines can be looked at as graphs with labeled edges. Yes, we're using "isomorphism" in the pop-compsci, Gödel-Escher-Bach sense.
One advantage of a graph database implementation over a traditional wiki implementation is in regard to querying along edges as opposed to following links. Which is to say that the edges of a graph database will tend to have richer semantics than a wiki's generic hyperlinks [but it is not to say that a graph database is necessarily better].
To put it another way, at best a link from a wiki page gets implied importance based on it's position within a document. A graph database edge can have many properties including "weight" or "relevance". Of course these could be added to wiki markup as properties, but there is a point at which the right tool is better than layered make-do's.
If desired, one can even make this easier to parse programmatically:
<a href="foo.html" class="ExampleCode">Hello world example</a>
<a href="bar.html" class="GrammarNotes">Grammar</a>
That allows for styling different types of links differently. Also, a wiki's backend software could extract separate indexes for sample code, grammar fragments, links to compiler source, etc. you could also easily include an attribute for, e.g. Click-through rate, and, if desired, style links accordingly.
In fact, the difference between a classical wiki and a graph database is, IMO, an implementation choice. If you want to process complex queries rapidly or a lot of your attributes aren't textual or aren't intended primarily for visual display, a graph database is more appropriate. If you want to serve standard web pages rapidly, storing the content as HTML may be more appropriate, even if that means that processing queries such as "give me all links to source code examples" run way more slowly.
Is this the new "Solution: Use Regular Expressions"?
There is a good reason tutorial style documentation is linear. Humans can keep track of what page of a book they are on, not which nodes of a graph they have visited.
Otherwise this doesn't add any new insight that wasn't there when the web was created. It's basically talking about hyperlinked documents. Identifying it as a graph doesn't help understand it any more than identifying the rotational groups of NaCl molecules lets me understand why they taste salty. It's useless structure/abstraction hunting.
I spent some time researching hypertext pre-web, and an old idea (Vannevar Bush old) is having "trails" through your document store, each basically giving a narrative one could follow. Sun used that terminology for their Java tutorials, though it seems the nodes along the trails are unique to a particular tutorial.
I could see something like this being useful for understanding a complex and complicated document like a programming language specification. The trails would show which sections and subsections work together to produce a particular behavior users should understand.
I've also seen dependency graphs given in the preface to certain math textbooks, which is nice when you know what it is you want to know (and I wish more textbooks would be available in hypertext form).
The idea of looking up particular sequences of documents to demonstrate actual behaviors is very compelling. Too often, documentation follows a precise but necessarily boring and unintuitive format. Having traces through documentation for common tasks would be very useful.
"We need engineers to not only feel that writing docs is their responsibility, but also to feel motivated to keep the quality of their docs high, and regularly maintain them." --- Can you share any specifics here? We're opening up tools, pulling notes from Jira, but the developer's docs still suck. There is rarely any meat to it, forcing us to become investigative journalists rather than tech editors.
That's happening already. To be more specific, any ideas on getting developers engaged in creating "quality" docs? They don't really care about them right now, its just a necessary administrative step on the path to commit.
When developers happen to be doing user support on the mailing list/forum/whatever you use, the importance of writing quality technical doc becomes more readily apparent to them.
The volume of questions diminishes as the doc improves, they become more interesting, and you can get the simple ones out of the way by sending a link without remorse because you know it does contain exactly what the user was looking for.
Of course it takes a little while for this to really engage, you'll need to kick a few people in the bottom to get past the initial investment, but in my experience it definitely works.
Start enforcing. Make PR's required for all new code, and reject PR's which aren't well-documented. Most developers can write good docs, they (we) just tend not to, until docs are treated as a primary priority by the rest of the team.
Good docs are in everyone's interest. It's hard enough for insiders to maintain code that isn't documented properly. Worse, it's nearly impossible for outsiders to come in and make changes later - at least not without a lot of wasted time.
I'm embarrassed of the state of this thing, but I think I'd be remiss if I didn't link to https://willshake.net/about
It's a graph of a system based (almost) entirely on documents. The documents create the documents. The documents create the graph. And of course, the documents contain the code.
I can't make enough disclaimers about how rough the documents are, and even the graph is starting to collapse under its own weight. But I think it gets the idea across. If I've learned one thing, it's that this style of programming---where you're forced to document as you go---is extremely work-intensive.
I don't mean a mediocre programmer who can write, I mean an excellent writer who excels at interviewing programmers, who can comprehend source code, and most of all is trained to be a writer?
So...use hyperlinks, basically? The web already works great as a graph structure for technical documentation. That's what it was made for, after all. :-)
Personally, I prefer the style which the GNU Coding Standards describe:
----
Programmers tend to carry over the structure of the program as the
structure for its documentation. But this structure is not necessarily
good for explaining how to use the program; it may be irrelevant and
confusing for a user.
Instead, the right way to structure documentation is according to the
concepts and questions that a user will have in mind when reading it.
This principle applies at every level, from the lowest (ordering
sentences in a paragraph) to the highest (ordering of chapter topics
within the manual). Sometimes this structure of ideas matches the
structure of the implementation of the software being documented--but
often they are different. An important part of learning to write good
documentation is to learn to notice when you have unthinkingly
structured the documentation like the implementation, stop yourself,
and look for better alternatives.
[…]
In general, a GNU manual should serve both as tutorial and reference.
It should be set up for convenient access to each topic through Info,
and for reading straight through (appendixes aside). A GNU manual
should give a good introduction to a beginner reading through from the
start, and should also provide all the details that hackers want. […]
That is not as hard as it first sounds. Arrange each chapter as a
logical breakdown of its topic, but order the sections, and write their
text, so that reading the chapter straight through makes sense. Do
likewise when structuring the book into chapters, and when structuring a
section into paragraphs. The watchword is, at each point, address the
most fundamental and important issue raised by the preceding text.
gnu is in many ways wonderful but documentation is not one of the ways. gnu's two docs challenges are (1) document the command-line flags for users and (2) document the code for contributing devs. I've never faced case 2 but wading through man pages for case 1 is less than awesome.
I agree that docs should answer the user's typical questions but gnu docs seldom do. Can you imagine trying to figure out gnu tar from the man page? You never would.
Doesn't help that search engines starting with G view queries like 'tail -f' as stopwords.
I dunno, I find them much better than most of the documentation I've worked with. I agree with you for beginners, since when I first started reading man pages and such, I wanted to rip my eyes out. But after a while, once I learned why the documentation was written the way it was, the flow of it started to make more and more sense. Though, in a lot of ways this comes from personal opinions that gnu tools and by extension, gnu/linux, should be difficult in the worse-is-better sense.
These days, when looking at documentation, my go-to example for awful documentation is salt. Because, well, this is utter bullshit:
I find GNU info more useful than man pages as documentation for those who are learning how to use a program. The documentation is structured and hyperlinked in a very convenient way. On the other hand, the terseness of man pages is more convenient for those who already mostly know the program, but need a reminder of minor details like the exact command line flag to enable a specific program option.
95% of the time when I'm opening a manpage I am looking for a particular command line option or syntax. With man pages I just hit / and then a relevant keyword and it jumps to the right section. With info pages I have to grok which section it might be in, then remember what arcane ctrl sequence follows links and then what sequence searches in the document then which sequence goes back because I guessed wrong.
I find manpages to be much more convienent, even though they are less structured.
"Topic-centric" is already a thing in technical writing. It produces those mystery-meat help systems you find in larger applications where you can find information about a specific piece of functionality piecemeal, and if you're lucky also a tutorial that tells you how to put it together into a larger workflow. If you're unlucky, it manages to summarize the parts you already knew without telling you about any details or pitfalls.
The graph is useful for note-taking and exploration, certainly, but it produces a design constraint that isn't always situationally appropriate. Binding things into a narrative can add a lot of value.
Technical writing traditions are mostly evidence-free bullshit that focusses on appearances at the expense of usefulness.
I usually find "official" technical docs very hard to read - much harder to follow and less useful than a typical how-to book.
Writing is not code. Human elements like humour and story-telling make technical content much easier to understand and learn.
And "topic centric" should be something that comes out of testing. User testing should note the most common user taskflows empirically, and write those up in the docs.
I propose we call these graphs "Hypertext". We could even create a markup language to write it. And a transfer protocol for resolving these hyperlinks by URLs.
Well... Table of contents and index are "different routes". Hyperlinks to sections that give more detail on a topic that is mentioned is a "different route". If you limit yourself to those, "just" is a reasonable word - but then the concept is pretty uninteresting, because people have been doing it for ages.
Instead my brain was totally distracted by those colorful nodes in the graph, it looks fancy but I remembered little afterwards. Maybe this is more helpful for those visual learners.
I've seen surprising pushback from non-technical managers over tree-structured information -- we're talking something as simple as a three-level nested markdown document. They'll say things like 'I can half understand it but my boss won't make the effort'.
If you think about how much energy your brain takes to unpack paragraph text into information, tree-structure should be clearer because visual boundaries correspond to topic / semantic boundaries, i.e. the brain can offload some parsing to the highly-evolved retina.
I don't have a good explanation for the preference for paragraph format in docs.
First of all, this article is an example of one whose first 80% could be cut. So many writers on the Web take so long to get to the point. I wish that they had learned the Inverted Pyramid style, which has been a tradition of newspapers.
Second, is what the writer describing something that would be met with a hyperlinked table of contents, like http://www.postgresql.org/docs/9.5/interactive/index.html, along with maybe each page hyperlinking to other pages where fit?
I would be willing to spend up to USD 50, for a chrome plugin (with an optional extra solution that worked on mobile) that automatically summarized articles into Inverted Pyramids. Of course, if you actually had this technology, my money wouldn't be essentially worthless given the much bigger and more lucrative markets you'd have available.
As an aside, I have thought this same thing. The non-inverted pyramid style is horrible and pervasive. I would pay $$/month to have technology or people summarize these things for me.
Most documents are already graphs of sorts. The fact that they are written down as they are is an implementation detail dictated by traditional physical constraints. I would image all authors have a "graph" in their heads before writing down the text. I'm pretty sure information are lost when this happens. I guess this is what the article tries to address.
I was really looking forward to checkout out the knowledge graph but zooming works horrible on using the touchpad. Did anybody else have that issue? It either zooms too much or way too little.
56 comments
[ 6.4 ms ] story [ 52.3 ms ] threadhttps://support.structr.com/knowledge-graph
I've read papers where the space of possible computations for a given (typically, toy, even loop-free) nondeterministic concurrent program is represented as a directed topological space (see “directed algebraic topology” for more information), but these spaces are more general than directed graphs.
I don't think you would need to deal with infinite graphs, as "arbitrarily large" should be able to cover all (finite) possible computations and/or representations.
My guess is that every graph may correspond to an infinite number (though, not necessarily every) of possible computations and/or representations, depending on which "correspondence function" is being used to analyze the graph (though there may be additional "correspondences" between those functions and/or their results).
The precise "information" associated to them could be "anything", but would be proscribed by the computation and/or representation being disccussed and the graph in question.
I'm even more annoyed by your use of the word “isomorphic”, which, FYI, doesn't mean “vaguely similar in some way I can't articulate”. It only makes sense two speak of two mathematical objects being “isomorphic” when they belong in the same category. What category do you have in mind, that includes both computations and graphs as objects, and what are the morphisms between them?
E.g.
Computation / representation:
Graph There is a way to produce the graph from the computation / representation and vice versa. There is a way to do that for every possible computation / representation and every possible graph (though, not necessarily with every pair).This could be described as a compiler or compiler-like. There are many interesting things to do with them, but in this example all that is needed to consider is the construction of an Abstract Syntax Tree from a string and an in-order tree walker that emits the contents of the nodes to an output string.
(1) A syntax tree isn't the same thing as a computation. Of course, you can produce computations by interpreting syntax trees, but: (a) It's perfectly possible for two distinct syntax trees to produce the same computation. [Say, by renaming all variables.] (b) It's also perfectly possible that interpreting the same syntax tree twice will produce completely different computations! [Say, if your language isn't pure.] Unsurprisingly, a syntax tree is a representation of syntax, not computation.
(2) Yes, I'm disappointed, because I expected your observation that “every computation (...) is isomorphic[sic] to some graph” to provide more insight than it turned out to.
Edit: Turned paraphrasing into literal quote.
0) You asked, "What information is associated to [nodes and edges]?". In this example, one piece of information is the direction of an edge.
1) I don't think I claimed they were the same. In fact, I am claiming that one can be represented by the other and vice versa. a) yes, that is part of the reason I conject that each graph may be associated with an "infinite number" of computations and/or representations b) also a reason -- there are perhaps an infinite number of languages, interpreters, compilers, etc. (some of which may produce the same result) for a given graph.
2) It was only an observation that the comment I responded to claimed only a subset of the truth. Anything done on a computer can be considered as a graph.
https://en.wikipedia.org/wiki/Graph_reduction https://en.wikipedia.org/wiki/Abstract_semantic_graph
Generally they're acyclic but some types of ASGs can represent recursive functions as cycles, so they are distinct from trees.
Basically, everything is in some way equivalent to some graph. Since anything is an example, it's difficult to say much without using an example, which then necessarily constrains the discussion.
It would be more useful if you presented an example computation or representation, then I could show you how to make and reverse an equivalent graph. (Which then might show you what information might be associated with nodes and edges.)
To put it another way, at best a link from a wiki page gets implied importance based on it's position within a document. A graph database edge can have many properties including "weight" or "relevance". Of course these could be added to wiki markup as properties, but there is a point at which the right tool is better than layered make-do's.
In fact, the difference between a classical wiki and a graph database is, IMO, an implementation choice. If you want to process complex queries rapidly or a lot of your attributes aren't textual or aren't intended primarily for visual display, a graph database is more appropriate. If you want to serve standard web pages rapidly, storing the content as HTML may be more appropriate, even if that means that processing queries such as "give me all links to source code examples" run way more slowly.
Is this the new "Solution: Use Regular Expressions"?
There is a good reason tutorial style documentation is linear. Humans can keep track of what page of a book they are on, not which nodes of a graph they have visited.
Otherwise this doesn't add any new insight that wasn't there when the web was created. It's basically talking about hyperlinked documents. Identifying it as a graph doesn't help understand it any more than identifying the rotational groups of NaCl molecules lets me understand why they taste salty. It's useless structure/abstraction hunting.
I could see something like this being useful for understanding a complex and complicated document like a programming language specification. The trails would show which sections and subsections work together to produce a particular behavior users should understand.
I've also seen dependency graphs given in the preface to certain math textbooks, which is nice when you know what it is you want to know (and I wish more textbooks would be available in hypertext form).
With that said, I'm so, so guilty. :)
The volume of questions diminishes as the doc improves, they become more interesting, and you can get the simple ones out of the way by sending a link without remorse because you know it does contain exactly what the user was looking for.
Of course it takes a little while for this to really engage, you'll need to kick a few people in the bottom to get past the initial investment, but in my experience it definitely works.
Good docs are in everyone's interest. It's hard enough for insiders to maintain code that isn't documented properly. Worse, it's nearly impossible for outsiders to come in and make changes later - at least not without a lot of wasted time.
I'm embarrassed of the state of this thing, but I think I'd be remiss if I didn't link to https://willshake.net/about
It's a graph of a system based (almost) entirely on documents. The documents create the documents. The documents create the graph. And of course, the documents contain the code.
I can't make enough disclaimers about how rough the documents are, and even the graph is starting to collapse under its own weight. But I think it gets the idea across. If I've learned one thing, it's that this style of programming---where you're forced to document as you go---is extremely work-intensive.
I don't mean a mediocre programmer who can write, I mean an excellent writer who excels at interviewing programmers, who can comprehend source code, and most of all is trained to be a writer?
----
Programmers tend to carry over the structure of the program as the structure for its documentation. But this structure is not necessarily good for explaining how to use the program; it may be irrelevant and confusing for a user.
Instead, the right way to structure documentation is according to the concepts and questions that a user will have in mind when reading it. This principle applies at every level, from the lowest (ordering sentences in a paragraph) to the highest (ordering of chapter topics within the manual). Sometimes this structure of ideas matches the structure of the implementation of the software being documented--but often they are different. An important part of learning to write good documentation is to learn to notice when you have unthinkingly structured the documentation like the implementation, stop yourself, and look for better alternatives.
[…]
In general, a GNU manual should serve both as tutorial and reference. It should be set up for convenient access to each topic through Info, and for reading straight through (appendixes aside). A GNU manual should give a good introduction to a beginner reading through from the start, and should also provide all the details that hackers want. […]
That is not as hard as it first sounds. Arrange each chapter as a logical breakdown of its topic, but order the sections, and write their text, so that reading the chapter straight through makes sense. Do likewise when structuring the book into chapters, and when structuring a section into paragraphs. The watchword is, at each point, address the most fundamental and important issue raised by the preceding text.
https://www.gnu.org/prep/standards/standards.html#GNU-Manual...
I agree that docs should answer the user's typical questions but gnu docs seldom do. Can you imagine trying to figure out gnu tar from the man page? You never would.
Doesn't help that search engines starting with G view queries like 'tail -f' as stopwords.
These days, when looking at documentation, my go-to example for awful documentation is salt. Because, well, this is utter bullshit:
$ man salt 2>/dev/null | wc -l
133324
I find manpages to be much more convienent, even though they are less structured.
The graph is useful for note-taking and exploration, certainly, but it produces a design constraint that isn't always situationally appropriate. Binding things into a narrative can add a lot of value.
I usually find "official" technical docs very hard to read - much harder to follow and less useful than a typical how-to book.
Writing is not code. Human elements like humour and story-telling make technical content much easier to understand and learn.
And "topic centric" should be something that comes out of testing. User testing should note the most common user taskflows empirically, and write those up in the docs.
This is kind of nit-picky, but I get bothered when someone uses the word "just" right before suggesting something that's really difficult to do.
If you think about how much energy your brain takes to unpack paragraph text into information, tree-structure should be clearer because visual boundaries correspond to topic / semantic boundaries, i.e. the brain can offload some parsing to the highly-evolved retina.
I don't have a good explanation for the preference for paragraph format in docs.
Second, is what the writer describing something that would be met with a hyperlinked table of contents, like http://www.postgresql.org/docs/9.5/interactive/index.html, along with maybe each page hyperlinking to other pages where fit?
For example if you have a technical article which references some concept there will likely be a link to another article which explains that concept.
Thus each page already acts as a node connected to other nodes by the links within it. No need for a more formalized graph.