Documentation principles

Last summer I learned from documentation by working on it without tools. Soon I will implement the documentation tools for Lever.

I learned that documentation tools should be sufficient but otherwise stay simple. Basis for good documentation is plain text. Despite that documentation should stay in a one place but appear in many places.

No docstrings

You'd expect documentation strings because Lever descends from Python.

def _():
    """such as this"""

Docstrings contribute to the size of the compiled binary and are too much detached from the main documentation. I think they are a nuisance. Therefore Lever doesn't have docstrings.

It is said that during documenting a project you will do lot of repetition to drive and teach the ideas. But since you're going to repeat yourself anyway why should you be stupid in your repetitions? Why should you repeat things in docstrings that belong into your documentation as well?

Connecting runtime to documentation

Runtime-available documentation is an useful feature during development. If I leave docstrings out it means I wouldn't have any runtime documentation at all. Instead of docstrings Lever connects runtime to documentation directly:

doc = path("doc:blub")

blubber = ():
    return 1

Modules have a postprocess condition: If a module has a .doc attribute and it is not null then the runtime will link the field to the members. If a member has a null field then it will do the same to its submembers.

As the outcome nearly every object in the runtime is linked to its documentation. The documentation will work both online&offline, though all the details aren't thought out yet.

Division of documentation

Lever has three methods of documentation by default.

The source code should be written in such manner that no explanation or meaning is demanded from someone who understands the language. Code should itself explain what it is doing.

Comments in the source code are for the person trying to understand how the program pieces together. Comments should explain any inobvious precondition there is. They should explain a reason for inobviously positioned variables.

In good Lever code the type of an object is self-explanatory, obvious from the context, or irrelevant. Therefore types should not be commented.

The documentation file should contain both the internals and external details of the program. The information relevant to a person is extracted by filtering the document.

The contents of the documentation file should be understandable to the average user of the library or the module the documentation is written for.

The documentation file may link to the tutorials and guides related to the library, but it may not contain them.

Each function entry in the documentation should supply short and succint explanation of what the function is used for. The formatting and grammar of the summary should make sense whenever the text appears under the name of the function.

Texopic

When it comes to the format of the documents, I were not satisfied to what is already available to me.

I wanted a human-readable plaintext format that is:

That didn't left me much choice, and every requirement here was necessary in a documentation system that does its job properly.

Time will show if my custom language for documentation was the right choice. But it is clear that there has not been much of widespread innovation in respect to documentation.

I expect that my applications increase the availability of the documentation by making it easier to maintain. Although it is not run by the computer, the documentation has same importance as the code.

Similar posts