Re: [SMW-devel] RFC: Technical documentation, installation instructions and release notes
Hi Jeroen, different answers for different questions: +1 to have detailed release notes in the source code (and nowhere else). The wiki will always have news items and SMW version pages that describe the main changes in a release; the release note file in the source can be linked from the wiki whenever more details are needed. -1 to removing installation notes from the wiki. This is where many users are looking for them. When I did releases, I copied the installation instructions from the source code to a new wiki page, and this was almost no extra work (most work was writing these instructions in plain text first, since it is a bit cumbersome to do this without markup). The real problem that you describe is that the installation notes in the source code do not always get updated properly. This needs to be the responsibility of whoever does the release. It is hard to do this in a very agile way with many developers, for several reasons: * a proper installation manual has a lot of text and some layout, which not every developer can be bothered with * the instructions often depend on many interconnected changes, so it is often not so clear who is in charge to write a change (and it is easy to pretend that one is not) * the instructions include things like version compatibility that are hard to fit into our own development process (for example, if MW releases a new version, then we need to say that we support it; but this is triggered by a change outside of our own code) * installation notes need to include (released) version numbers of dependencies, while master could refer to git branches/revisions of other extensions instead If you want, we could strip down the notes in git to a bare minimum and refer to a wiki page for the final details. This might make it easier for developers to keep the notes updated without getting into extnsive user documentation writing. +0 to keep API documentation in the source. Most things are better documented in the source, the Web API is self-documenting, and the phpdocs should be better than wiki for code documentation. However, some general entry points and high-level introductions to these features and resources should be in the wiki, so people know where to go. However, hooks (=strings in some PHP function) do not appear in the source docs or API docs in a natural way; they might be better documented on the wiki, like MW does it. Cheers, Markus On 05/11/13 09:57, Jeroen De Dauw 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 > documenta
Re: [SMW-devel] RFC: Technical documentation, installation instructions and release notes
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 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
Re: [SMW-devel] RFC: Technical documentation, installation instructions and release notes
Hi Jeroen! In my opinion the less documentation goes with source code - the better. Documentation must be easy to edit and it's not easy to do anything in git. I propose to store only release notes in git and everything else on the wiki. I think it's especially bad to store installation instructions there: they're provided in different languages and are a subject of constant improvement. - Yury Katkov, WikiVote On Tue, Nov 5, 2013 at 12:57 PM, Jeroen De Dauw 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 > -- 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
[SMW-devel] RFC: Technical documentation, installation instructions and release notes
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
