Technical Documentation Should Be a Graph

[unfamiliar]

>Solution: Use a Graph

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.

[kmill]

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).

[andrewflnr]

You have a problem, so you think "I'll represent this as a graph." Now you have O(n^2) problems.

With that said, I'm so, so guilty. :)

[dchuk]

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

[brudgers]

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.

[jsprogrammer]

Every computation and/or representation is isomorphic to some (hypothetical) graph.

[teddyh]

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.

https://www.gnu.org/prep/standards/standards.html#GNU-Manual...

[awinter-py]

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.

[combatentropy]

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?

[nvader]

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.

[collyw]

From Neo4J. When all you have is a hammer..... (second time I have posted that today)

[twic]

When you're selling hammers ...

[SloopJon]

In fairness, this is a guest post by Structr describing the ideas underlying their knowledge graph:

https://support.structr.com/knowledge-graph

[chipsy]

"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.

[TheOtherHobbes]

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.

[nostrademons]

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. :-)

[pluma]

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.

[edgyswingset]

> Instead of forcing readers to follow a single, linear, flat sequence of sections, just offer different routes between articles or items.

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.

[AnimalMuppet]

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.

[awinter-py]

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.

[jenncarlos]

"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.

[epc]

Have you considered hiring a technical writer?

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?

[nathancahill]

Write the documentation alongside the code it documents?

[ageofwant]

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.

[cha5m]

Isn't this already how much documentation is structured implicitly?

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.

[yranadive]

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.

[ausjke]

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.

[EGreg]

Simply use columns like MacOS's column view. And mark the items already visited.

[ColCh]

Hey, main point of article is "use mindmap". It's a graph too

[snappy173]

graph sounds complicated. what about a web?