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 <jeroended...@gmail.com> 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 > -- > ------------------------------------------------------------------------------ November Webinars for C, C++, Fortran Developers Accelerate application performance with scalable programming models. Explore techniques for threading, error checking, porting, and tuning. Get the most from the latest Intel processors and coprocessors. See abstracts and register http://pubads.g.doubleclick.net/gampad/clk?id=60136231&iu=/4140/ostg.clktrk _______________________________________________ Semediawiki-devel mailing list Semediawiki-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/semediawiki-devel
