Re: [yast-devel] moving linuxrc documentation to github
On 12/01/2016 03:46 PM, Devin Waas wrote: > Hello YaSTheads, > > in an effort to make documentation updated and consistent, I'm > considering moving the linuxrc entries of the wiki[1] to github. > > The motivations are: > 1) we'll have docs and source in the same place (thus reducing the > scattering of information) > 2) we'll be able to render the docs on readthedocs.io/wherever > 3) we'll have the benefits of a version control system (history/reviews) Leaving the technical benefits aside, there is something like a rule of thumb we are following with the YaST documentation: - developer oriented documentation -> use git exactly as you suggested - user oriented documentation -> keep the historical and well known opensuse wiki I can't wait for the day in which the openSUSE project completely change the documentation approach/tooling (there have been several attempts like adopting activedoc in doc.opensuse.org), but as long as wiki.o.o continues being the expected place for documentation, we should probably play by the rules. Cheers. -- Ancor González Sosa YaST Team at SUSE Linux GmbH -- To unsubscribe, e-mail: yast-devel+unsubscr...@opensuse.org To contact the owner, e-mail: yast-devel+ow...@opensuse.org
Re: [yast-devel] moving linuxrc documentation to github
Hello, On Dec 1 15:46 Devin Waas wrote (excerpt): moving the linuxrc entries of the wiki[1] to github. ... https://en.opensuse.org/SDB:Linuxrc Don't forget to adapt all openSUSE and SUSE 'internal' stuff (e.g. manuals and whatever) that links to it, cf. https://en.opensuse.org/Special:WhatLinksHere/SDB:Linuxrc And don't forget to also adapt all 'external' stuff like any pages on whatever other web severs that link to it ;-) Seriously: You would at least need to change https://en.opensuse.org/SDB:Linuxrc into some kind of automated forwarder that can somehow redirect to the new place where the actual content is. (I don't know how to do that with a Wiki.) Kind Regards Johannes Meixner -- SUSE LINUX GmbH - GF: Felix Imendoerffer, Jane Smithard, Graham Norton - HRB 21284 (AG Nuernberg) -- To unsubscribe, e-mail: yast-devel+unsubscr...@opensuse.org To contact the owner, e-mail: yast-devel+ow...@opensuse.org
Re: [yast-devel] moving linuxrc documentation to github
On 01.12.2016 15:46, Devin Waas wrote: If no one has anything to say against this, I'll probably start this weekend. Please leave your suggestions if you have any. :) [1] Linuxrc wiki entry ~~ https://en.opensuse.org/SDB:Linuxrc Please be aware that whenever somebody moves Wiki content around, this means breaking everybody's bookmarks, which is almost as good as deleting the documentation permanently. I don't mean to say that the old SDB-based wiki articles are the ultimate solution (to the contrary - it's hard to find out what is up to date and what is outdeated), but it's been around for a while, word has spread that it exists, and there are a gazillion links to that place from everywhere - other SDB / Wiki articles, people's blogs, Bugzilla, whatever. Those links will then all become invalid. As a matter of fact, this is the reason why I am very reluctant to write anything in any Wiki any more: I find myself cheated out of the benefits of my own documentation because that stuff constantly gets rearranged and moved around by people just meaning well: "The road to hell is paved with good intentions" etc. ;-) As for benefits of version control: Well, every Wiki has that. It's just a bit different from Git. And as for GitHub Wikis: They are problematic in that you lose the connection to the original when you fork a GitHub repo; the original and the forks will inevitably diverge, and hardly anybody will notice. Those Wikis are just not as well integrated into GitHub as all the rest (well, maybe we are just spoiled by how well everything else at GitHub works). If we absolutely need to move that linuxrc documentation from the old, well-known place to someplace else: Did you check out https://pages.github.com/ ? I don't know how different that is from the plain GitHub Wiki that comes with every GitHub project by default. It might be worthwhile looking at (if the format is simple enough like the usual markdown they use everywhere else). Kind regards -- Stefan Hundhammer YaST Developer SUSE Linux GmbH GF: Felix Imendörffer, Jane Smithard, Graham Norton; HRB 21284 (AG Nürnberg) Maxfeldstr. 5, 90409 Nürnberg, Germany -- To unsubscribe, e-mail: yast-devel+unsubscr...@opensuse.org To contact the owner, e-mail: yast-devel+ow...@opensuse.org
[yast-devel] moving linuxrc documentation to github
Hello YaSTheads, in an effort to make documentation updated and consistent, I'm considering moving the linuxrc entries of the wiki[1] to github. The motivations are: 1) we'll have docs and source in the same place (thus reducing the scattering of information) 2) we'll be able to render the docs on readthedocs.io/wherever 3) we'll have the benefits of a version control system (history/reviews) If no one has anything to say against this, I'll probably start this weekend. Please leave your suggestions if you have any. :) [1] Linuxrc wiki entry ~~ https://en.opensuse.org/SDB:Linuxrc -- Devin Waas QA Engineer for Maintenance - SUSE Enterprise Storage SUSE LINUX, s.r.o. CORSO II Krizikova 148/34, 186 00 Prague 8 Czech Republic -- To unsubscribe, e-mail: yast-devel+unsubscr...@opensuse.org To contact the owner, e-mail: yast-devel+ow...@opensuse.org
