[SMW-devel] RFC: Technical documentation, installation instructions and release notes

[Jeroen De D. <jer...@gm...>]

Hey,

We have been both shipping documentation together with the source code (as
text files) and providing it on the SMW wiki since I joined the project. I
see some problems with this.

If the documentation is at both places, it doubles the maintenance effort.
Given we have quite little resources to spend on this already, this does
not help the quality of the documentation in question. Looking at the docs
bundled with the source code, it seems that a lot of it is quite out of
date, incomplete and sometimes plain wrong.

A more focused effort seems to be in order. I propose that for the
following items are only bundled with the source code and not duplicated
elsewhere:

* Release notes
* Core installation instructions
* Technical documentation on our APIs (and no, I' not talking just about
our web API)

If this is bundled with the source code, we can keep it fully up to date
the whole time. If someone adds a new feature, they should also update the
release notes. If someone changes an API, they should update the
documentation. Relevant buzzword: "Agile documentation". Another advantage
comes from the documentation not just being up to date with the latest
development, it's also always correct for the version of the code you have.
So if you get the previous release, you'll have the correct documentation
for it, rather then something that reflects all the development that
happened since. Yet another plus of having this together with the source is
that people are not forced to hit our wiki. Offline use is possible. And
it's just nice to have this in git together with the code, so no additional
infrastructure is needed or relied upon.

The SMW wiki would not contain a copy of this documentation. It can refer
to it, and it can expand on it. Or provide translations. Technical
tutorials, full installation guides and so on would also remain on the SMW
wiki.

What needs to happen to get there? We already made most of the change, just
not explicitly. The biggest violators of this policy where the release
notes, and our API documentation. The release notes for 1.8 where actually
already referenced from the SMW wiki at some point, by embedding the
contents of the file from our git repo in the wiki page [0]. And we now
have some documentation on our APIs in the "docs" folder, written in
markdown format.

Making such a change more explicit means that it is clear the documentation
bundled with the source should be updated timeline. It also makes it clear
no effort should be spend in duplicating it on wiki.

I've been following such a practice myself for several other projects and
am quite happy with it. Examples:

* https://github.com/wikimedia/mediawiki-extensions-SubPageList
* https://github.com/wikimedia/mediawiki-extensions-Diff

Feedback is welcome.

[0] This is no longer the case as this broke due to WMF breaking the URLs
via which our source could be accessed. That has been resolved in the
meantime, so we can use this model again for the 1.9 release notes.

Cheers

--
Jeroen De Dauw
http://www.bn2vs.com
Don't panic. Don't be evil. ~=[,,_,,]:3
--