Sunday, July 10, 2016¶
About software documentation¶
Thiago Nascimento, in his article Software without documentation - Legend or Reality? deplores that free software often lacks good documentation.
Thiago, I agree with you about the lack itself. Yes, there are many programmers who write great software and who lose motivation or even fail when they are asked to write also the documention about their work. But this is not deplorable, it is normal. Writing software and writing about software are two very different things, and most people are more or less focussed in one of them.
No, I don’t think that team leaders and project managers usually underestimate the importance of documentation for the maintenance and the life cycle of a software project.
The deplorable thing –if you want something to deplore– might be that team leaders and project managers don’t always have a spirit of sharing. But even this is actually normal as long as most of us believe that software can be seen as private property (Why software must be free).
I liked your classification of “documentation types”, it inspired me to write my own (which is very similar):
Functional documentation describes the features of the software using a language that is comprehensible by project stakeholders and developers.
Technical documentation describes the technical aspects of the software in a language used mainly by the developers themselves.
User documentation describes the handling of the software by the user.
Historic documentation describes the evolution of the software and the lessons learned throughout its construction.
Loading demo fixtures¶
Ticket #1029 caused quite some email traffic between
Grigorij, Hamza and me. It took us some time to understand that the
error occurs when the current directory contains an
__init__.py file and a file
demo.py. You can reproduce
it manually like this:
$ cd lino_book/projects/min1/settings $ python ../manage.py initdb_demo
Unlike one of my theories at some moment, the error works
independently of the
Note that there are different ways of running the
cd to the project directory and and run python manage.py initdb_demo:
$ cd ~/repositories/book/lino_book/projects/max $ python manage.py initdb_demo
do not cd into any directory, but specify the settings module:
$ django-admin.py initdb_demo --settings=lino_book.projects.max.settings.demo
$ cd ~/repositories/book $ inv prep
The error was so difficult to reproduce because it does not occur in
cases 1 and 2, and even in case 3 only when
The reason for this error is complex:
DJANGO_SETTINGS_MODULEis in a settings package (which is the case for many but not all demo projects), then the
project_dirpoints to the
settingssubdir of what we would intuitively consider the project directory.
for mod in ctx.demo_projects: m = import_module(mod) p = m.SITE.cache_dir or m.SITE.project_dir with cd(p): # run initdb_demo ...
Using m.SITE.cache_dir or m.SITE.project_dir as current directory is a bit dangerous because it causes magic effects.