Scott Penrose

Documentation is code

Scott is an expert software developer with over 30 years experience, specialising in education, automation and remote data.

Why do we treat documentation different to code?

When it comes to the code, everyone slowly moves it and fixes it. If a driver is out of date and not working, it may get disabled until it gest fixed, but it always remains. Even if it gets completely deprecated, it is still in the version control system.

I have worked on projects where a new person has taken over the documentation, and deleted wiki documents - permanently - because "they are out date".

It is unfortunately that the wiki (and I am generalising here because there are alternatives) in this case is also the VCS, so the data is lost forever. Yes backups etc, but this is over a long period, so even the backups have the pages removed.

No one would dream of doing this is the code word. But people just don't care about documentation, and worse, lots of people, especially technical and programmers, don't care about the huge work that has gone into those documents (generalisation of course, since I am both technical and a programmer that does care).

  • Open Source
  • Documentation