
Technical Documentation Should Be a Graph - vigorouscoding
http://neo4j.com/blog/technical-documentation-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).

~~~
quietplatypus
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.

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

~~~
Someone
I don't see it is that different. A wiki page typically assigns human-readable
properties through its text. You don't write

    
    
      <a href="foo.html">Read more</a>
      <a href="bar.html">Read more</a>
    

but:

    
    
      <a href="foo.html">Example code</a>
      <a href="bar.html">Grammar</a>
    

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.

------
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...](https://www.gnu.org/prep/standards/standards.html#GNU-Manuals)

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

~~~
bpchaps
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:

$ man salt 2>/dev/null | wc -l

133324

~~~
catnaroek
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.

~~~
jandrese
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.

------
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](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.

~~~
karmacondon
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.

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

~~~
twic
When you're _selling_ hammers ...

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

~~~
nathancahill
Write the documentation alongside the code it documents?

~~~
jenncarlos
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.

~~~
dandelany
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.

~~~
TheOtherHobbes
There will be mutinous grumbling. But yes - this.

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.

------
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?

