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

[Yury K. <kat...@gm...>]

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 <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
> --
>
> ------------------------------------------------------------------------------
> 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
> Sem...@li...
> https://lists.sourceforge.net/lists/listinfo/semediawiki-devel
>