[RFC] Wiki replacement plan
I'd like to offer a proposal for a path forward here, merging ideas and concerns everyone's put in, particularly Maren's feedback on my initial proposal in the previous wiki thread. Apologies ahead of time for the length, as usual brevity escapes me.
Wiki Replacement Plan ---------------------- #0 - No change to the current wiki until Inkscape's codebase is migrated to git. So, probably no change until March or so. Thus, people considering using the wiki for things right now, should proceed with doing those things.
#1 - Application documentation and reference source files are moved to Inkscape's share directory in VCS. Extension references, output format details, tutorials, usage advice, and so on. This will be shipped with the application, and probably worth rendering in some web-viewable format as well. Nearly all of this will be worth translating.
#2 - Strictly user-facing pages in the wiki are moved to the main website. High level project info, roadmaps, user-oriented FAQs, community resources, and so on. If a page requires advanced styling or layout functionality in our current mediawiki, that would be a strong indication it should be moved to our Django. This will obviously take time and effort but can be tackled bit by bit. Most of this is worth translating.
Finalized release notes will become part of the releases app; this will support html and translations.
#3 - Static coder-facing documentation should be moved to Inkscape's doc/ directory. This includes anything that documents implemented designs, protocols, and other assorted functionality. It also includes coder tutorials and guidelines. Generally materials that can be considered "finished" and worth keeping for reference value. This doesn't include unimplemented ideas/proposals, nor anything that is obsolete or that we're keeping simply for historical purposes. Little of this will be worth translating.
#4 - Dynamic development pages are moved to the git*b wiki. This includes design mockups, development plans, todo lists, architectural brainstorming, infrastructure refactoring proposals and the like. A lot of the stuff currently registered as blueprints, that are adequately well fleshed out and that may be worth including in our official roadmap, should also move here. None of this should be translated.
The release notes under development for the trunk codebase are drafted here in this wiki. Perhaps eventually we'll move editing to the releases app.
This also includes organizational documentation for the Inkscape board, pages relating to fundraising, hackfest planning, and so on.
#5 - Obsolete pages are left in the current wiki, but "mothballed" for historical reference.
#6 - A "Community Wiki" will be established with open access for members of the wider Inkscape community, to use as a freeform collaborative editing space. There would not be rules about what can and can't go in here, but this is where folks would go to do collaborative brainstorming, flesh out raw ideas, and share random wishes and bits of information not ready or suitable for inclusion in any of the above. It should be easy to register for and easy to edit, but also robust against spam. All other pages not covered by 2-5 above, will end up here.
As a general rule of thumb, if a page in the Community Wiki is important enough to be worth translating, or if we find ourselves linking to the page frequently, then that is a sign the page ought to be promoted and moved elsewhere.
This could be an updated MediaWiki like we currently have, however I'd like to see thought given to alternative solutions, such as a Django wiki plugin that allows tighter integration with the website, or even using an externally maintained wiki service. It could also be a special Git*b project with really lax rules for committing. Whatever we pick, the important things are that it's widely available to all, easy to use, and very light on rules or imposed structure.
#7 - Feature requests and wishlist changes, eventually will move into a future project management system on the website (I envision something that couples bug tracker style commenting with wiki like editing within a Blueprints-type tracking system). This is probably a few years out though so we'll need to keep using #4 devel wiki in the meantime.
Let me know what you think, and please poke holes. If there are no red flags raised, we can proceed with this plan subsequent to our move to git.
Thanks, Bryce
#2 - Strictly user-facing pages in the wiki are moved to the main
website. High level project info, roadmaps, user-oriented FAQs, community resources, and so on. If a page requires advanced styling or layout functionality in our current mediawiki, that would be a strong indication it should be moved to our Django. This will obviously take time and effort but can be tackled bit by bit. Most of this is worth translating.
Finalized release notes will become part of the releases app; this will support html and translations. ____________________________________________________________
I'm not as familiar with the wiki as Maren, but as far as I know #2 is almost completely finished. The only user-facing info still in the wiki, that I know of, is the Extension Repository page. It's kind of in limbo right now, because it's part of the project which Mark Schafer is working on, to get as many extensions as possible uploaded to InkSpaces/gallery (and he and Maren, and to a much lesser extent, me, are using the wiki for that).
I'm not sure about Roadmaps being user-facing. But I guess there are some pages which are benficial to both sides (user/developer). But if it is user-facing, I don't think it's on the website yet. About putting it on the website, I'd worry it might generate complaints, unless it's strongly worded in the introduction about how it's set more in jello than stone.
Hhmm....I see those user-facing pages still have not been deleted! I deleted them once, after I put the info on the website (on Martin's ok) but they came back. Then we learned that there is some upper-level wiki editor which (or who?) doesn't allow pages to be deleted. But I thought we finally solved that, and had deleted them. I guess not.
(On the main wiki page, the User Documentation section, the link to "International and Local Communities" probably should link to the Community page on the website. Just like "Tutorials" links to the Learn page. Seems like I fixed that once before, myself....hhmm.)
All best, brynn
-----Original Message----- From: Bryce Harrington Sent: Sunday, January 29, 2017 1:36 AM To: inkscape-devel@...6... Subject: [Inkscape-devel] [RFC] Wiki replacement plan
I'd like to offer a proposal for a path forward here, merging ideas and concerns everyone's put in, particularly Maren's feedback on my initial proposal in the previous wiki thread. Apologies ahead of time for the length, as usual brevity escapes me.
Wiki Replacement Plan ---------------------- #0 - No change to the current wiki until Inkscape's codebase is migrated to git. So, probably no change until March or so. Thus, people considering using the wiki for things right now, should proceed with doing those things.
#1 - Application documentation and reference source files are moved to Inkscape's share directory in VCS. Extension references, output format details, tutorials, usage advice, and so on. This will be shipped with the application, and probably worth rendering in some web-viewable format as well. Nearly all of this will be worth translating.
#2 - Strictly user-facing pages in the wiki are moved to the main website. High level project info, roadmaps, user-oriented FAQs, community resources, and so on. If a page requires advanced styling or layout functionality in our current mediawiki, that would be a strong indication it should be moved to our Django. This will obviously take time and effort but can be tackled bit by bit. Most of this is worth translating.
Finalized release notes will become part of the releases app; this will support html and translations.
#3 - Static coder-facing documentation should be moved to Inkscape's doc/ directory. This includes anything that documents implemented designs, protocols, and other assorted functionality. It also includes coder tutorials and guidelines. Generally materials that can be considered "finished" and worth keeping for reference value. This doesn't include unimplemented ideas/proposals, nor anything that is obsolete or that we're keeping simply for historical purposes. Little of this will be worth translating.
#4 - Dynamic development pages are moved to the git*b wiki. This includes design mockups, development plans, todo lists, architectural brainstorming, infrastructure refactoring proposals and the like. A lot of the stuff currently registered as blueprints, that are adequately well fleshed out and that may be worth including in our official roadmap, should also move here. None of this should be translated.
The release notes under development for the trunk codebase are drafted here in this wiki. Perhaps eventually we'll move editing to the releases app.
This also includes organizational documentation for the Inkscape board, pages relating to fundraising, hackfest planning, and so on.
#5 - Obsolete pages are left in the current wiki, but "mothballed" for historical reference.
#6 - A "Community Wiki" will be established with open access for members of the wider Inkscape community, to use as a freeform collaborative editing space. There would not be rules about what can and can't go in here, but this is where folks would go to do collaborative brainstorming, flesh out raw ideas, and share random wishes and bits of information not ready or suitable for inclusion in any of the above. It should be easy to register for and easy to edit, but also robust against spam. All other pages not covered by 2-5 above, will end up here.
As a general rule of thumb, if a page in the Community Wiki is important enough to be worth translating, or if we find ourselves linking to the page frequently, then that is a sign the page ought to be promoted and moved elsewhere.
This could be an updated MediaWiki like we currently have, however I'd like to see thought given to alternative solutions, such as a Django wiki plugin that allows tighter integration with the website, or even using an externally maintained wiki service. It could also be a special Git*b project with really lax rules for committing. Whatever we pick, the important things are that it's widely available to all, easy to use, and very light on rules or imposed structure.
#7 - Feature requests and wishlist changes, eventually will move into a future project management system on the website (I envision something that couples bug tracker style commenting with wiki like editing within a Blueprints-type tracking system). This is probably a few years out though so we'll need to keep using #4 devel wiki in the meantime.
Let me know what you think, and please poke holes. If there are no red flags raised, we can proceed with this plan subsequent to our move to git.
Thanks, Bryce
------------------------------------------------------------------------------ Check out the vibrant tech community on one of the world's most engaging tech sites, SlashDot.org! http://sdm.link/slashdot _______________________________________________ Inkscape-devel mailing list Inkscape-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/inkscape-devel
On Sun, Jan 29, 2017 at 04:24:39AM -0700, brynn wrote:
#2 - Strictly user-facing pages in the wiki are moved to the main
website. High level project info, roadmaps, user-oriented FAQs, community resources, and so on. If a page requires advanced styling or layout functionality in our current mediawiki, that would be a strong indication it should be moved to our Django. This will obviously take time and effort but can be tackled bit by bit. Most of this is worth translating. Finalized release notes will become part of the releases app; this will support html and translations.
I'm not as familiar with the wiki as Maren, but as far as I know #2 is almost completely finished.
Ok, great. In poking around a bit I see a lot of wiki pages being properly marked as no longer relevant, with pointer to an appropriate page on the Inkscape website. So this all looks quite good.
The only user-facing info still in the wiki, that I know of, is the Extension Repository page. It's kind of in limbo right now, because it's part of the project which Mark Schafer is working on, to get as many extensions as possible uploaded to InkSpaces/gallery (and he and Maren, and to a much lesser extent, me, are using the wiki for that).
Ok cool. I like that in the gallery that there is an example image or video for each extension. The descriptions look a bit more complete too.
There's a fair bit of other extension-related information in the wiki currently, beyond details on extensions themselves. But I suspect most of that can be folded into some of the other described sections. For instance, docs related to how to write extensions probably would be best housed in a developers' manual.
I'm not sure about Roadmaps being user-facing. But I guess there are some pages which are benficial to both sides (user/developer). But if it is user-facing, I don't think it's on the website yet. About putting it on the website, I'd worry it might generate complaints, unless it's strongly worded in the introduction about how it's set more in jello than stone.
I do need to go through and revamp it majorly, I haven't worked on it in years and I'm sure it's completely inaccurate. And you're right it's of interest to everyone, it's not strictly just user-facing. But it is high profile and the range of people who need to edit it are relatively limited so for these reasons I think the website is a more appropriate home for it. Anyway, for now let's not worry about it. When I get around to updating it we can take another look at placement.
Hhmm....I see those user-facing pages still have not been deleted! I deleted them once, after I put the info on the website (on Martin's ok) but they came back. Then we learned that there is some upper-level wiki editor which (or who?) doesn't allow pages to be deleted. But I thought we finally solved that, and had deleted them. I guess not.
The approach of leaving them in place but link to the replacement page in the website seems suitable. I wonder if there's a subtle way we could mark links on the top page of the wiki to indicate these kinds of pages.
(On the main wiki page, the User Documentation section, the link to "International and Local Communities" probably should link to the Community page on the website. Just like "Tutorials" links to the Learn page. Seems like I fixed that once before, myself....hhmm.)
Bryce
All best, brynn
-----Original Message----- From: Bryce Harrington Sent: Sunday, January 29, 2017 1:36 AM To: inkscape-devel@...6... Subject: [Inkscape-devel] [RFC] Wiki replacement plan
I'd like to offer a proposal for a path forward here, merging ideas and concerns everyone's put in, particularly Maren's feedback on my initial proposal in the previous wiki thread. Apologies ahead of time for the length, as usual brevity escapes me.
Wiki Replacement Plan
#0 - No change to the current wiki until Inkscape's codebase is migrated to git. So, probably no change until March or so. Thus, people considering using the wiki for things right now, should proceed with doing those things.
#1 - Application documentation and reference source files are moved to Inkscape's share directory in VCS. Extension references, output format details, tutorials, usage advice, and so on. This will be shipped with the application, and probably worth rendering in some web-viewable format as well. Nearly all of this will be worth translating.
#2 - Strictly user-facing pages in the wiki are moved to the main website. High level project info, roadmaps, user-oriented FAQs, community resources, and so on. If a page requires advanced styling or layout functionality in our current mediawiki, that would be a strong indication it should be moved to our Django. This will obviously take time and effort but can be tackled bit by bit. Most of this is worth translating.
Finalized release notes will become part of the releases app; this will support html and translations.#3 - Static coder-facing documentation should be moved to Inkscape's doc/ directory. This includes anything that documents implemented designs, protocols, and other assorted functionality. It also includes coder tutorials and guidelines. Generally materials that can be considered "finished" and worth keeping for reference value. This doesn't include unimplemented ideas/proposals, nor anything that is obsolete or that we're keeping simply for historical purposes. Little of this will be worth translating.
#4 - Dynamic development pages are moved to the git*b wiki. This includes design mockups, development plans, todo lists, architectural brainstorming, infrastructure refactoring proposals and the like. A lot of the stuff currently registered as blueprints, that are adequately well fleshed out and that may be worth including in our official roadmap, should also move here. None of this should be translated.
The release notes under development for the trunk codebase are drafted here in this wiki. Perhaps eventually we'll move editing to the releases app. This also includes organizational documentation for the Inkscape board, pages relating to fundraising, hackfest planning, and so on.#5 - Obsolete pages are left in the current wiki, but "mothballed" for historical reference.
#6 - A "Community Wiki" will be established with open access for members of the wider Inkscape community, to use as a freeform collaborative editing space. There would not be rules about what can and can't go in here, but this is where folks would go to do collaborative brainstorming, flesh out raw ideas, and share random wishes and bits of information not ready or suitable for inclusion in any of the above. It should be easy to register for and easy to edit, but also robust against spam. All other pages not covered by 2-5 above, will end up here.
As a general rule of thumb, if a page in the Community Wiki is important enough to be worth translating, or if we find ourselves linking to the page frequently, then that is a sign the page ought to be promoted and moved elsewhere. This could be an updated MediaWiki like we currently have, however I'd like to see thought given to alternative solutions, such as a Django wiki plugin that allows tighter integration with the website, or even using an externally maintained wiki service. It could also be a special Git*b project with really lax rules for committing. Whatever we pick, the important things are that it's widely available to all, easy to use, and very light on rules or imposed structure.#7 - Feature requests and wishlist changes, eventually will move into a future project management system on the website (I envision something that couples bug tracker style commenting with wiki like editing within a Blueprints-type tracking system). This is probably a few years out though so we'll need to keep using #4 devel wiki in the meantime.
Let me know what you think, and please poke holes. If there are no red flags raised, we can proceed with this plan subsequent to our move to git.
Thanks, Bryce
Check out the vibrant tech community on one of the world's most engaging tech sites, SlashDot.org! http://sdm.link/slashdot _______________________________________________ Inkscape-devel mailing list Inkscape-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/inkscape-devel
Ok, great. In poking around a bit I see a lot of wiki pages being
properly marked as no longer relevant, with pointer to an appropriate page on the Inkscape website. So this all looks quite good.
Yes, they're well marked (I think thanks to Maren).
The approach of leaving them in place but link to the replacement page
in the website seems suitable. I wonder if there's a subtle way we could mark links on the top page of the wiki to indicate these kinds of pages.
The green "banner" seems to work ok. At least ok for me.
There's a fair bit of other extension-related information in the wiki
currently, beyond details on extensions themselves. But I suspect most of that can be folded into some of the other described sections. For instance, docs related to how to write extensions probably would be best housed in a developers' manual.
Yeah, I wouldn't want to lose those. We get so many questions in forums that I can't answer. "Developers' manual".....hhmm. Hhmm.... Almost said "hmmm" again. I guess I think of the entire wiki as being the developers' manual. Is someone actually working on such a thing? I haven't heard about it.
Would those wiki pages about how to write an extension be considered static? (i.e. going to the git wiki or docs dir?) They probably don't change a whole lot, but still sometimes, I guess.
I do need to go through and revamp it majorly, I haven't worked on it in
years and I'm sure it's completely inaccurate. And you're right it's of interest to everyone, it's not strictly just user-facing. But it is high profile and the range of people who need to edit it are relatively limited so for these reasons I think the website is a more appropriate home for it. Anyway, for now let's not worry about it. When I get around to updating it we can take another look at placement.
Well, someone's been updating the Roadmap. I remember looking at it before and after the first hackfest, and someone has kept it relatively current.
I could put on my to-do list, to move it to the website. But it could be several months before it makes it to the top. Let me know when you finish, and maybe it will be near the top of my list, by then.
All best, brynn
-----Original Message----- From: Bryce Harrington Sent: Monday, January 30, 2017 11:39 AM To: brynn Cc: inkscape-devel@...6... Subject: Re: [Inkscape-devel] [RFC] Wiki replacement plan
On Sun, Jan 29, 2017 at 04:24:39AM -0700, brynn wrote:
#2 - Strictly user-facing pages in the wiki are moved to the main
website. High level project info, roadmaps, user-oriented FAQs, community resources, and so on. If a page requires advanced styling or layout functionality in our current mediawiki, that would be a strong indication it should be moved to our Django. This will obviously take time and effort but can be tackled bit by bit. Most of this is worth translating. Finalized release notes will become part of the releases app; this will support html and translations.
I'm not as familiar with the wiki as Maren, but as far as I know #2 is almost completely finished.
Ok, great. In poking around a bit I see a lot of wiki pages being properly marked as no longer relevant, with pointer to an appropriate page on the Inkscape website. So this all looks quite good.
The only user-facing info still in the wiki, that I know of, is the Extension Repository page. It's kind of in limbo right now, because it's part of the project which Mark Schafer is working on, to get as many extensions as possible uploaded to InkSpaces/gallery (and he and Maren, and to a much lesser extent, me, are using the wiki for that).
Ok cool. I like that in the gallery that there is an example image or video for each extension. The descriptions look a bit more complete too.
There's a fair bit of other extension-related information in the wiki currently, beyond details on extensions themselves. But I suspect most of that can be folded into some of the other described sections. For instance, docs related to how to write extensions probably would be best housed in a developers' manual.
I'm not sure about Roadmaps being user-facing. But I guess there are some pages which are benficial to both sides (user/developer). But if it is user-facing, I don't think it's on the website yet. About putting it on the website, I'd worry it might generate complaints, unless it's strongly worded in the introduction about how it's set more in jello than stone.
I do need to go through and revamp it majorly, I haven't worked on it in years and I'm sure it's completely inaccurate. And you're right it's of interest to everyone, it's not strictly just user-facing. But it is high profile and the range of people who need to edit it are relatively limited so for these reasons I think the website is a more appropriate home for it. Anyway, for now let's not worry about it. When I get around to updating it we can take another look at placement.
Hhmm....I see those user-facing pages still have not been deleted! I deleted them once, after I put the info on the website (on Martin's ok) but they came back. Then we learned that there is some upper-level wiki editor which (or who?) doesn't allow pages to be deleted. But I thought we finally solved that, and had deleted them. I guess not.
The approach of leaving them in place but link to the replacement page in the website seems suitable. I wonder if there's a subtle way we could mark links on the top page of the wiki to indicate these kinds of pages.
(On the main wiki page, the User Documentation section, the link to "International and Local Communities" probably should link to the Community page on the website. Just like "Tutorials" links to the Learn page. Seems like I fixed that once before, myself....hhmm.)
Bryce
All best, brynn
Am 31.01.2017 um 12:29 schrieb brynn:
Ok, great. In poking around a bit I see a lot of wiki pages being
properly marked as no longer relevant, with pointer to an appropriate page on the Inkscape website. So this all looks quite good.
Yes, they're well marked (I think thanks to Maren).
- I think we need to credit Sylvain and su_v for most of this. Just as I didn't 'tweak the translations page to perfection' - I don't remember ever having changed anything on it. I don't know who wrote it.
The extensions listing pages in the Wiki are a WIP, they're still being checked, so definitely a Wiki thing. I think someone had planned to contact the authors, and to ask them if they would like to publish their extension at inkscape.org... (and if they don't answer, just to publish them there, if they work and licence permits).
There's a fair bit of other extension-related information in the wiki
currently, beyond details on extensions themselves. But I suspect most of that can be folded into some of the other described sections. For instance, docs related to how to write extensions probably would be best housed in a developers' manual.
Yeah, I wouldn't want to lose those. We get so many questions in forums that I can't answer. "Developers' manual".....hhmm. Hhmm.... Almost said "hmmm" again. I guess I think of the entire wiki as being the developers' manual. Is someone actually working on such a thing? I haven't heard about it.
- I'd rather be daring, and put that info about how to write an extension into the user manual part. It's surprisingly well documented, and it's usually advanced users, (like me) who want to write their own extensions to fulfill their specific needs, or to fill in for missing functionality.
These are often not the people who would or could work on the application code itself.
Script extensions, for me, fall into the same category as custom pattern files, icon sets, symbol sets, custom templates, custom filters, custom markers, custom keymaps, palette files, etc. (but most of those don't have easily accessible documentation - we usually give people a link to external tutorials, if there are any).
@Brynn: It's possible to auto-create a 'developer's manual' from special comments (docstrings) in the code. For that, the code needs to be documented inside the code files.
Regards, Maren
Hi Bryce,
as you seem to have made up your mind about shutting down the MediaWiki despite peoples concerns (which I still don't think is a good idea to start with for the reasons explained before) let's start from there...
I'm sorry to sound negative here but with the current plan I see a *lot* of work heading our way that will not result in any improvement over our current infrastructure at all. At the very best (if - and only if - we have the manpower to get this done properly) it might become equivalent. As the past has shown the spare time to fiddle with documentation is a *very* rare good and in my humble opinion we should abstain from spending it all on administrative tasks like splitting, moving, copyediting, whatever.
Now to poke some holes:
#1 - Application documentation and reference source files are moved to Inkscape's share directory in VCS. Extension references, output format details, tutorials, usage advice, and so on. This will be shipped with the application, and probably worth rendering in some web-viewable format as well. Nearly all of this will be worth translating.
I honestly have no idea what exactly you have in mind here. For "extension reference" do you mean "user documentation for existing extensions" (we have [1] but this is nothing that is ready for a wider audience, let alone translation) or "developer documentation on how to write extensions" (then I don't think it fits the category). Tutorials are already in share and all the rest sounds very vague.
[1] http://wiki.inkscape.org/wiki/index.php/Extension_reference
#2 - Strictly user-facing pages in the wiki are moved to the main website. High level project info, roadmaps, user-oriented FAQs, community resources, and so on. If a page requires advanced styling or layout functionality in our current mediawiki, that would be a strong indication it should be moved to our Django. This will obviously take time and effort but can be tackled bit by bit. Most of this is worth translating.
Finalized release notes will become part of the releases app; this will support html and translations.
This is one point I fully agree with you, but as brynn noted with the exception of release notes this is pretty much the current state.
#3 - Static coder-facing documentation should be moved to Inkscape's doc/ directory. This includes anything that documents implemented designs, protocols, and other assorted functionality. It also includes coder tutorials and guidelines. Generally materials that can be considered "finished" and worth keeping for reference value. This doesn't include unimplemented ideas/proposals, nor anything that is obsolete or that we're keeping simply for historical purposes. Little of this will be worth translating.
When is coder-facing documentation ever "static"? The current reality looks more like: developer A adds a feature, developer B sees the need to document it some and adds a very short notice in the Wiki, developer C wants to use the feature and is struggling with the rare information and then hopefully adds enough information to be useful, developer D finds it and is finally able to work with it and fixes the remaining inaccuracies, typos and grammatical errors; only then it starts to become useful, but at that time a code change probably made it outdated or even obsolete. The thing that probably comes closest to what I understand you have in mind is [2] (including subpages). Does that mean we remove that information from the website (I don't think so)? Does that mean we duplicate that content (We partially have that in the Wiki and it's problematic at best as it effectively doubles the maintenance work and is likely to have one of the copies outdated)?
[2] https://inkscape.org/en/develop/
#4 - Dynamic development pages are moved to the git*b wiki. This includes design mockups, development plans, todo lists, architectural brainstorming, infrastructure refactoring proposals and the like. A lot of the stuff currently registered as blueprints, that are adequately well fleshed out and that may be worth including in our official roadmap, should also move here. None of this should be translated.
The release notes under development for the trunk codebase are drafted here in this wiki. Perhaps eventually we'll move editing to the releases app. This also includes organizational documentation for the Inkscape board, pages relating to fundraising, hackfest planning, and so on.
Again, what are "dynamic" development pages. As noted before I'd consider basically everything developer-related dynamic and I could live with having that all in a git*b wiki (do we really still call it git*b? For that decision it seems some people have already made up their mind, too). If you ask me that is actually the way I'd prefer and the only reasonable solution: Everything developer-related goes into a gitlab wiki where everyone is welcome (and encouraged!) to improve content. An arbitrary splitting of developer-documentation will only result in duplication (with your suggestion we'd have Website, VCS, developer Wiki, maybe even some pages in the community Wiki you mention below. That's three locations to many!).
#5 - Obsolete pages are left in the current wiki, but "mothballed" for historical reference.
If we want to draw the line and shut down the MediaWiki do it correctly! The old content should not be easily accessible. If there is important content it *has* to be moved so that basically nobody will ever have a reason to look at the old Wiki again. If we can't manage that then we should not attempt the move at all (hence my initial doubts!). The worst case scenario I see is that Google indexes the old Wiki and people continue to work with that information while the new information is hidden somewhere deep in the VCS or gitlab.
#6 - A "Community Wiki" will be established with open access for members of the wider Inkscape community, to use as a freeform collaborative editing space. There would not be rules about what can and can't go in here, but this is where folks would go to do collaborative brainstorming, flesh out raw ideas, and share random wishes and bits of information not ready or suitable for inclusion in any of the above. It should be easy to register for and easy to edit, but also robust against spam. All other pages not covered by 2-5 above, will end up here.
As a general rule of thumb, if a page in the Community Wiki is important enough to be worth translating, or if we find ourselves linking to the page frequently, then that is a sign the page ought to be promoted and moved elsewhere. This could be an updated MediaWiki like we currently have, however I'd like to see thought given to alternative solutions, such as a Django wiki plugin that allows tighter integration with the website, or even using an externally maintained wiki service. It could also be a special Git*b project with really lax rules for committing. Whatever we pick, the important things are that it's widely available to all, easy to use, and very light on rules or imposed structure.
No! Thinking about yet another Wiki is just stupid (sorry). Where do we save *any* resources by decommissioning the old MediaWiki only to create another (potentially Media-)Wiki, a gitlab developer Wiki and even more documentation in VCS? In my opinion the Wiki was always a community project! Maybe it was too hard to get an account there, but than we should work on solving that. Why should users be disallowed to update developer documentation? There's almost never enough time to write developer documentation and I'd say everyone willing to work on it should be allowed to do so. After all (at least with MediaWiki - I don't know about gitlab wikis) it's trivial to revert changes if they ever should introduce wrong information (which I assume to be highly unlikely). If you really intend to create a wiki space for users (I'm unsure about the content that might go there... and if I'm unsure how should users know?) then simply have that inside one (and only one!) Wiki. (MediaWiki could offer categories, subpages or even an own namespace for that)
#7 - Feature requests and wishlist changes, eventually will move into a future project management system on the website (I envision something that couples bug tracker style commenting with wiki like editing within a Blueprints-type tracking system). This is probably a few years out though so we'll need to keep using #4 devel wiki in the meantime.
What's wrong with the current approach of having that in the normal bugtracker (aside from the obvious shortcomings of Launchpad itself)? If we move to gitlab we could simply use gitlab issues for that (they allow markdown which should be enough "wiki-like" editing). Why try to create even more infrastructure for something that we already have plenty of solutions for free? Don't get me wrong: What you're envisioning sounds cool, but in practice I think it just won't work. Where should we take the developer resources from to implement such a system? Where should we take the resources from to triage all these things (I guess this will ultimately fall back to the bug team)? How do you expect users to properly differentiate between bugs and feature requests when even developers sometimes struggle to label some request. I really don't think a separation between bugs and features will work unless there's an easy way to transfer between them (in my own projects on GitHub I simply use "bug" and "enhancement" labels for that nowadays as it's usually the best approach to assign this status when triaging a request).
Let me know what you think, and please poke holes. If there are no red flags raised, we can proceed with this plan subsequent to our move to git.
Thanks, Bryce
I hope you won't take any of that personal (it's certainly not intended that way!) but I really don't feel this is the correct direction...
Best Regards, Eduard
Hi Eduard,
as you seem to have made up your mind about shutting down the MediaWiki despite peoples concerns (which I still don't think is a good idea to start with for the reasons explained before) let's start from there...
That's my call actually. The machine is ancient and osuosl are itching to get rid of it. We're using it for very little compared to the machine's power and I'd prefer if it were possible to fold in our services to use the website and the gitlab wiki.
*very* rare good and in my humble opinion we should abstain from spending it all on administrative tasks like splitting, moving, copyediting, whatever.
The content doesn't need to be copy edited. A lot of pages need to be archived and I think a archiving by default position would be a good start. Take what we need, as we know we need it.
I honestly have no idea what exactly you have in mind here. For "extension reference" do you mean "user documentation for existing extensions" (we have [1] but this is nothing that is ready for a wider audience, let alone translation) or "developer documentation on how to write extensions" (then I don't think it fits the category). Tutorials are already in share and all the rest sounds very vague.
[1] http://wiki.inkscape.org/wiki/index.php/Extension_reference
Extensions shouldn't be in the wiki anyway. Either they're for user consumption and should be on the website (where anyone can post one) or if committed they should be documented alongside the codebase. If in the future we split out our extensions repository, that's a task for another day.
#2 - Strictly user-facing pages in the wiki are moved to the main website. High level project info, roadmaps, user-oriented FAQs,
I'd vote roadmaps aren't user facing documents. They're develop documents. We may want to write news or campaigns about them for the website though.
but at that time a code change probably made it outdated or even
obsolete.
A lot of coder related documentation is actually in-line, some of it is build instructions, "getting started" that sort of thing. Generated docs aren't for committing and I expect we wouldn't actually have that many docs in the git repository, at least not separate from code.
But that'll be for us to proof as we see what kinds of pages are being archived out of the wiki. We'd only put things in the git repo if it made sense and I think Bryce is making room, even if the room isn't going to be used.
Again, what are "dynamic" development pages. As noted before I'd consider basically everything developer-related dynamic and I could live with having that all in a git*b wiki (do we really still call it git*b? For that decision it seems some people have already made up their mind, too).
I'd just keep these on the GitLab. If they're developer related and people are collaborating, the markdown wiki should be fine. For faster collabs we can still use google docs and paste into the wiki when they get stable (by which I mean edit time goes into the minutes as apposed to seconds.
Don't forget on GitLab you can save User wiki pages, and I recommend we encourage their use for drafting if people don't want to muck up the project wiki.
If you ask me that is actually the way I'd prefer and the only reasonable solution: Everything developer-related goes into a gitlab
Agreed, this is a good plan.
If we want to draw the line and shut down the MediaWiki do it correctly! The old content should not be easily accessible. If there is important content it *has* to be moved so that basically nobody will ever have a reason to look at the old Wiki again. If we can't manage that then we should not attempt the move at all (hence my initial doubts!). The worst case scenario I see is that Google indexes the old Wiki and people continue to work with that information while the new information is hidden somewhere deep in the VCS or gitlab.
No the media wiki content can be saved into a read-only directory on inkscape.org, so we can reffer to it but no editing. If edits are needed, then the content is moved to the right place.
No! Thinking about yet another Wiki is just stupid (sorry). Where do we save *any* resources by decommissioning the old MediaWiki only to create another (potentially Media-)Wiki, a gitlab developer Wiki and even more documentation in VCS?
I agree. We have enough tools to do this without a MediaWiki of any kind.
I hope you won't take any of that personal (it's certainly not intended that way!) but I really don't feel this is the correct direction...
No, good concerns, highly appreciated.
Best Regards, Martin Owens
Hi Martin,
Am 30.01.2017 um 21:16 schrieb Martin Owens:
Hi Eduard,
as you seem to have made up your mind about shutting down the MediaWiki despite peoples concerns (which I still don't think is a good idea to start with for the reasons explained before) let's start from there...
That's my call actually. The machine is ancient and osuosl are itching to get rid of it. We're using it for very little compared to the machine's power and I'd prefer if it were possible to fold in our services to use the website and the gitlab wiki.
That's unfortunate but absolutely understandable. I guess moving to another server / a virtualized server was not an option?
*very* rare good and in my humble opinion we should abstain from
spending it all on administrative tasks like splitting, moving, copyediting, whatever.
The content doesn't need to be copy edited. A lot of pages need to be archived and I think a archiving by default position would be a good start. Take what we need, as we know we need it.
I'm disliking the term "archiving" a bit, see below.
I honestly have no idea what exactly you have in mind here. For "extension reference" do you mean "user documentation for existing extensions" (we have [1] but this is nothing that is ready for a wider audience, let alone translation) or "developer documentation on how to write extensions" (then I don't think it fits the category). Tutorials are already in share and all the rest sounds very vague.
[1] http://wiki.inkscape.org/wiki/index.php/Extension_reference
Extensions shouldn't be in the wiki anyway. Either they're for user consumption and should be on the website (where anyone can post one) or if committed they should be documented alongside the codebase. If in the future we split out our extensions repository, that's a task for another day.
I think we're talking about different things here: As far as I can see the Wiki currently contains a) documentation on built-in extensions (that was the link), b) documentation on how to write an extension, and c) a list of third-party extensions. While a) is obviously user-facing and therefore would fit on the webpage I don't think it's complete enough yet and needs work. b) is even harder - personally I'd keep it in a Wiki so it can be improved continuously by everyone (as I'd prefer for all developer documentation), bryce would like to put it into the VCS's developer documentation if I understood him correctly and Maren even considered having it on the Website! Extensions themselves obviously do not belong in any Wiki.
#2 - Strictly user-facing pages in the wiki are moved to themain website. High level project info, roadmaps, user-oriented FAQs,
I'd vote roadmaps aren't user facing documents. They're develop documents. We may want to write news or campaigns about them for the website though.
but at that time a code change probably made it outdated or even
obsolete.
A lot of coder related documentation is actually in-line, some of it is build instructions, "getting started" that sort of thing. Generated docs aren't for committing and I expect we wouldn't actually have that many docs in the git repository, at least not separate from code.
But that'll be for us to proof as we see what kinds of pages are being archived out of the wiki. We'd only put things in the git repo if it made sense and I think Bryce is making room, even if the room isn't going to be used.
All right, that sounds reasonable. I was a bit afraid that we'd try to somehow put everything relevant into /doc but I honestly don't think that would work but instead only create a graveyard of outdated information that many people wouldn't even know existed.
Again, what are "dynamic" development pages. As noted before I'd consider basically everything developer-related dynamic and I could live with having that all in a git*b wiki (do we really still call it git*b? For that decision it seems some people have already made up their mind, too).
I'd just keep these on the GitLab. If they're developer related and people are collaborating, the markdown wiki should be fine. For faster collabs we can still use google docs and paste into the wiki when they get stable (by which I mean edit time goes into the minutes as apposed to seconds.
Don't forget on GitLab you can save User wiki pages, and I recommend we encourage their use for drafting if people don't want to muck up the project wiki.
Sounds good, but I assume the encouraging part will be vital. I don't think many people used their user page on the MediaWiki...
If you ask me that is actually the way I'd prefer and the only reasonable solution: Everything developer-related goes into a gitlab
Agreed, this is a good plan.
If we want to draw the line and shut down the MediaWiki do it correctly! The old content should not be easily accessible. If there is important content it *has* to be moved so that basically nobody will ever have a reason to look at the old Wiki again. If we can't manage that then we should not attempt the move at all (hence my initial doubts!). The worst case scenario I see is that Google indexes the old Wiki and people continue to work with that information while the new information is hidden somewhere deep in the VCS or gitlab.
No the media wiki content can be saved into a read-only directory on inkscape.org, so we can reffer to it but no editing. If edits are needed, then the content is moved to the right place.
This is something I'm very skeptical about: - How should people know where to search for Information if we have a half-dead Wiki and a not-yet-alive Wiki side-by-side? - How do we prevent potentially outdated information on the read-only page from being used in error (i.e. who would be able to delete/edit that information?) - If we put a huge sign on top "Warning! Outdated!" nobody will take that information serious (how could they?). If we don't people might not be aware they're browsing an archived read-only version of the page that in fact *can* be outdated. - How do you intend to motivate people to work on the new Wiki if there's "some" content already available on the old Wiki? (I'm imagining scenes like "there's some information on the old Wiki which is mostly up-to-date; unfortunately nobody's able to update the few errors since it's a read-only version; unfortunately we also did not have the time to transfer it to the new Wiki, yet").
No! Thinking about yet another Wiki is just stupid (sorry). Where do we save *any* resources by decommissioning the old MediaWiki only to create another (potentially Media-)Wiki, a gitlab developer Wiki and even more documentation in VCS?
I agree. We have enough tools to do this without a MediaWiki of any kind.
I hope you won't take any of that personal (it's certainly not intended that way!) but I really don't feel this is the correct direction...
No, good concerns, highly appreciated.
Best Regards, Martin Owens
Regards, Eduard
Am 31.01.2017 um 20:12 schrieb Eduard Braun:
I think we're talking about different things here: As far as I can see the Wiki currently contains a) documentation on built-in extensions (that was the link), b) documentation on how to write an extension, and c) a list of third-party extensions. While a) is obviously user-facing and therefore would fit on the webpage I don't think it's complete enough yet and needs work. b) is even harder - personally I'd keep it in a Wiki so it can be improved continuously by everyone (as I'd prefer for all developer documentation), bryce would like to put it into the VCS's developer documentation if I understood him correctly and Maren even considered having it on the Website!
- Just a small correction: It's already there, for the most part: https://inkscape.org/en/develop/extensions/ (Martin wrote that page)
But what I meant was to put those Wiki pages with additional info about inx files etc. into a manual, or the 'user documentation'.
Regards, Maren
On Tue, 2017-01-31 at 20:12 +0100, Eduard Braun wrote:
That's unfortunate but absolutely understandable. I guess moving to another server / a virtualized server was not an option?
Are you volunteering? ;-) getting services out of osuosl has been almost impossible. I'd rather be able to show them we can cut back and not have to have replacements.
I think we're talking about different things here: As far as I can see the Wiki currently contains a) documentation on built-in extensions (that was the link), b) documentation on how to write an extension, and c) a list of third-party extensions. While a) is obviously user-facing and therefore would fit on the webpage I don't think it's complete enough yet and needs work. b) is even harder - personally I'd keep it in a Wiki so it can be improved continuously by everyone (as I'd prefer for all developer documentation), bryce would like to put it into the VCS's developer documentation if I understood him correctly and Maren even considered having it on the Website! Extensions themselves obviously do not belong in any Wiki.
a) goes to the inkscape-docs project b) goes to the gitlab wiki c) goes to the inkscape.org website
Links between them are useful. We don't /have/ to keep things in a silo, the extensions on the website can link to creating extensions. The inkscape-docs are built and already shown on the website so continue that.
- If we put a huge sign on top "Warning! Outdated!" nobody will take
that information serious (how could they?). If we don't people might not be aware they're browsing an archived read-only version of the page that in fact *can* be outdated.
People will make mistakes, that is something we'll always have. Having the the button redirect to a page explaining the process would be helpful for anonymous helpers. But most people are going to be bryce ;- ).
scenes like "there's some information on the old Wiki which is mostly up-to-date; unfortunately nobody's able to update the few errors since it's a read-only version; unfortunately we also did not have the time to transfer it to the new Wiki, yet").
If there's not enough time to copy and paste it raw into a gitlab wiki, then it mustn't be a very important change. We're not expecting every page to be a perfect copy, we'll lose things, but then gain the ability to edit them. Nothing is perfect, but it's a chance to make it better.
If I must make a button on every page that say "Move this to GitLab" and "Move this to the website" I'll add those. Not perfect, but maybe helpful.
Best Regards, Martin Owens
participants (5)
-
Bryce Harrington -
brynn -
Eduard Braun -
Maren Hachmann -
Martin Owens