HomePage RecentChanges Real Time Documentation

The topic of real time documentation has come up a lot lately. Use of IDEs that do real time compile (see XXX), or real time documentation (see Light Table).

Greate concept

Conceptuatlly this is great. Colour syntax highlighting helps us to see what we are typing, even picks up mistakes as you go. Documentation at a press of a buttons is also very neat.

Distraction?

One concern I have is over distraction. Human eyes go to movement. Anything that changes on a screen, unecessarily is bad. This is why advertising on web sites often moves. It is also why Blink tag is dead.

Quick access to help is essential, not sure if real time is? To be thought about further and experimented with.

Every Context

Having documentation in your editor is handy but hardly the only place it is required. It probably comes from the way people code, or more specifically what people code. A person coding all day in Visual Studio is probably happy reading all thd coumentation in one place. Many other people may be coding all day in VIM and still be happy with their content in one place, as they use the same editor for different components (e.g. Makefile, C, Perl, JS, CSS, HTML).

Not just programming

My problem is that I don't tend to work in a very nicely defined single environment. Let me give a computer and a non-computer example:

Debugging

You just tested for a HTTP error, only now you just received another one in your log file. What is it? I remember 301, and 303, but what is 302? Oh yes. You need to know in your code and in your logs.

The same applies to system admin. You might do a heap of automation in your code and while tesitng need to set some more entries in /proc.

Electronic Design

The documentation I just used in my C/C++ code 5 minutes ago I still now need while I am doing my circuit design in Eagle. Woops now I need that same documentation on my bench with my soldering iron.

Problems

Each coding system I use has its own documentaiton. Here are some of the examples I use every day.

Electronics

If I purchase a IMU, I will most likely have the following documentation to deal with:

Solutions

Repository

Can we create one big repository that we can either cache or access remotely?

Use Cases

Embedded designer - Using an IMU

As an example I am going to use the MinIMU-9 Polou IMU

Here is some of the documentation you might need for this component.

These are just the raw URLs. Mostly they are PDF. The 3 arduino libraries though have their own (or mostly do not have their own !) documentation. Often they only have examples.

Some other documentation that comes up in an example like this:

Physical and Logical places this documentation will be used:

What other documentation could we add to this list:

What if you are using a different embedded CPU - libraries for raw ARM, libraries for embedded linux (e.g. Beagle Bone) and more.

Just this one simple component and all of the references requires a huge amount of documentation and references.

Software error:

Can't locate object method "endform" via package "CGI" at /data/scott.dd.com.au/wiki/modules/search.pl line 15.

For help, please send mail to the webmaster (webmaster@dd.com.au), giving this error message and the time and date of the error.