From: James HK <jam...@gm...> - 2013-11-05 09:20:26
|
Hi, +1 When I started re-factoring classes and objects, I first thought that the SMW wiki would be the right place for keeping track of such effort but it soon became apparent that maintaining such information on-wiki is not worth energy and therefore I retreated from the wiki as technical documentation source and instead started to use the /docs/ for document that is directly linked to code it represents. Cheers On 11/5/13, Jeroen De Dauw <jer...@gm...> wrote: > 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 > -- > |