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:
This project is part of:
Hack Week 11
Activity
Comments
-
almost 11 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.
-
almost 11 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]
-
almost 11 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
Advent of Code: The Diaries by amanzini
Description
It was the Night Before Compile Time ...
Hackweek 25 (December 1-5) perfectly coincides with the first five days of Advent of Code 2025. This project will leverage this overlap to participate in the event in real-time.
To add a layer of challenge and exploration (in the true spirit of Hackweek), the puzzles will be solved using a non-mainstream, modern language like D, Crystal, Gleam or Zig.
The primary project intent is not just simply to solve the puzzles, but to exercise result sharing and documentation. I'd create a public-facing repository documenting the process. This involves treating each day's puzzle as a mini-project: solving it, then documenting the solution with detailed write-ups, analysis of the language's performance and ergonomics, and visualizations.
|
\ ' /
-- (*) --
>*<
>0<@<
>>>@<<*
>@>*<0<<<
>*>>@<<<@<<
>@>>0<<<*<<@<
>*>>0<<@<<<@<<<
>@>>*<<@<>*<<0<*<
\*/ >0>>*<<@<>0><<*<@<<
___\\U//___ >*>>@><0<<*>>@><*<0<<
|\\ | | \\| >@>>0<*<0>>@<<0<<<*<@<<
| \\| | _(UU)_ >((*))_>0><*<0><@<<<0<*<
|\ \| || / //||.*.*.*.|>>@<<*<<@>><0<<<
|\\_|_|&&_// ||*.*.*.*|_\\db//_
""""|'.'.'.|~~|.*.*.*| ____|_
|'.'.'.| ^^^^^^|____|>>>>>>|
~~~~~~~~ '""""`------'
------------------------------------------------
This ASCII pic can be found at
https://asciiart.website/art/1831
Goals
Code, Docs, and Memes: An AoC Story
Have fun!
Involve more people, play together
Solve Days 1-5: Successfully solve both parts of the Advent of Code 2025 puzzles for Days 1-5 using the chosen non-mainstream language.
Daily Documentation & Language Review: Publish a detailed write-up for each day. This documentation will include the solution analysis, the chosen algorithm, and specific commentary on the language's ergonomics, performance, and standard library for the given task.