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).
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.
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.
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:
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.
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.
Each coding system I use has its own documentaiton. Here are some of the examples I use every day.
- Perl - nicely defined as POD, can access 99% of documentation with perldoc.
- C++ - almost no standard way of getting access to documentation
- Javscript - some libraries (e.g. ExtJS) have a nice interface (but s ee integration in Solutions)
- Electronic, especially Embedded - Layers of abstraction issue (see Electronics below), no standard access.
If I purchase a IMU, I will most likely have the following documentation to deal with:
- The IMU main document - often a single PDF.
- The IMU schematic and board files
- Each component on the IMU Datasheet - could be 3 or more major components.
- One or more libraries - maybe an Arduino or other Embedded C++ library to access either the whole IMU board, or possibly even separately for each component.
- Single documentation / repsoitory
- Can then be used by Vim plugin, Light Table, Eclipse, etc
- Command line shortcuts
- Pretty obvious, command line to get to your information
- iPhone/Android app
- Essential to carry around documentation with me
- Keyboard and macro jumps.
- Examples to embed in each IDE, Editor, etc.
Can we create one big repository that we can either cache or access remotely?
- Needs a good classification and category system
- Must support common conventions (e.g. variable X in functio Y in class Z).
- Must be locally cachable - this could mean you need to individually download the PDFs (at least partially or fully autoamtically)
- Each thing in the DB is just a refernce:
- Must get to the thing (hopefully URL) and the part (PDF or HTML is easy)
- User selection
- Ability for the user to select categories or individual items as favorites, or even for specific devices
- E.g. All of a language
- Index and data downloadable
- Data where possible - e.g. copy of Perl and CPAN documentation
- Automatic downloader where possible - e.g. to PDF of Datasheets
- Manually helpers where possible - e.g. Give a list of references to help users download, then automatically discover and reorganise these files - this would be very useful for data sheets etc which require login or NDA to download.
- Encourage manufacturers to contribute to the list
- Think... structured wikipedia or Freebase
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.
- http://www.pololu.com/catalog/product/1265 - purchase and supplier
- http://www.pololu.com/file/0J491/L3G4200D.pdf - LSG4200D data sheet
- http://www.pololu.com/file/0J514/LSM303DLM.pdf - LSM303DLM data sheet
- https://github.com/pololu/L3G4200D - L3G4200D Arduino Library
- https://github.com/pololu/LSM303 - LSM303 Arduino Library
- https://github.com/pololu/MinIMU-9-Arduino-AHRS - Combined AHRS Aruino Library
- http://www.pololu.com/file/0J502/MinIMU-9_schematic.pdf - Schematic
- http://www.pololu.com/file/0J435/UM10204.pdf - i2c bus specification
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:
- Designer Notes
- Board errors
- Atlernatives - especially important when stocks could be low
- Limitations / Special notes - e.g. GPS details on Aerial types and configurations.
Physical and Logical places this documentation will be used:
- Soldering it up? What was pin 11 for?
- Testing. What pin do we look at the clock?
- Code editor
- Writing the code you may need to set a specific register over SPI.
- Schematic / Board layout editor
- Lots of information here?
- More links too - e.g. a specific component library for Eagle with logical and physical connections
- Documentation editor
- Finished product, documentor wants to reference temperature range for each component?
- What to test?
- No point in testing beyond limits (e.g. vibration).
What other documentation could we add to this list:
- Hazards - pretty common with physical development
- Manufacturing standard - is there lead?
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.