I like to try out if it is possible to write a program that does not have any kind of the traditionally separated documentation (like external files that contain the documentation texts or comments in the program code). Instead all documentation must be implemented as code at the same place where the matching functiomnality is implemented (i.e. each function implements also its documentation). In the end the user should get only the executable that he can run to let it do the intended functionality and also to provide any kind of documentation. What I do not want is a dumb '--help' option that lets the program spit out its built-in documentation. What I would like to have is that the user can run the executable in some kind of self-inspecting way. I mean: While it does the intended functionality, it can also provide documentation so that the user can explore the program while running it. In the end the user experience should be more like a text adventure ;-)

Looking for hackers with the skills:

documentation adventure usability

This project is part of:

Hack Week 11

Activity

  • over 9 years ago: jsmeix added keyword "usability" to this project.
  • over 9 years ago: jsmeix added keyword "adventure" to this project.
  • over 9 years ago: jsmeix added keyword "documentation" to this project.
  • over 9 years ago: jsmeix liked this project.
  • over 9 years ago: jsmeix started this project.
  • over 9 years ago: jsmeix originated this project.

  • Comments

    • jsmeix
      over 9 years ago by jsmeix | Reply

      I mean the same basic idea as "literate programming" but now all must be source code for the executable (in literate programming the documentation is no source code for the actual executable). I.e. no special preprocessor/generator in between - just only plain source code is allowed for all and everything.

    • jreidinger
      over 9 years ago by jreidinger | Reply

      I think you can look at rspec which is quite close to idea of joining tests and documentation together. Also more highlevel is cucumber. Another option is to run examples in documentation as tests which we did in ycp-killer - [https://github.com/yast/y2r/blob/master/spec/y2r_spec.md]

    • jsmeix
      over 9 years ago by jsmeix | Reply

      A short note what I accomplished and what I didn't:

      I made a C program (plain C no special add-ons) that implemets the idea in a very basic way. But I needed most of the time to implement basic infrastructure and helper functions. The current state is very unfinished and not yet suitable to be presented to an audience.

    Similar Projects

    Deep clean-up of the Uyuni documentation files by omaric

    Project Description

    This project is plann...