Dear developers and wiki enthusiasts,
Our current wiki hosted on wiki.inkscape.org is doing ok, but is running on an old machine that the hosting provider OSUOSL would like to retire if at all possible.
Since we are moving to Git*b, this is an opportunity to also move the wiki to that service. This decreases our system-admin burden and the resources we ask from osuosl.
It would also say that our wiki is more of a developer/contributor focused effort, leaving user content to the website. I expect things like hackfest planning and other plumbing to continue to use a wiki system.
The process of moving it would entail waiting until our code is on git*b and then convert each of the existing pages from MediaWiki syntax to Markdown syntax.
A script such as this https://bitbucket.org/wikier/mw2md%C2%A0could be used, but testing would be needed to see what kind of output we got.
For all people involved in using and editing the wiki, I'd like your thoughts on how we should manage our wiki service going forwards.
Thank you all.
Best Regards, Martin Owens Website Administrator Hat
MD is slightly easier to use than MW from a pure syntax standpoint, so the amount of contribution to the wiki would likely increase somewhat in volume if do such a move.
I also think it makes sense to release resources from the Inkscape community by doing this move, if the old wiki requires administration resources (creating user accounts seems to be a common task happening on the mailing list - this noise would just go away e.g.).
My 2 ören (there's 100 ören in a Sweden krona),
Mvh
/Olof ----------------- Är du systemutvecklare? Spana in https://cilamp.se
On 10 January 2017 at 21:32, Martin Owens <doctormo@...400...> wrote:
Dear developers and wiki enthusiasts,
Our current wiki hosted on wiki.inkscape.org is doing ok, but is running on an old machine that the hosting provider OSUOSL would like to retire if at all possible.
Since we are moving to Git*b, this is an opportunity to also move the wiki to that service. This decreases our system-admin burden and the resources we ask from osuosl.
It would also say that our wiki is more of a developer/contributor focused effort, leaving user content to the website. I expect things like hackfest planning and other plumbing to continue to use a wiki system.
The process of moving it would entail waiting until our code is on git*b and then convert each of the existing pages from MediaWiki syntax to Markdown syntax.
A script such as this https://bitbucket.org/wikier/mw2md could be used, but testing would be needed to see what kind of output we got.
For all people involved in using and editing the wiki, I'd like your thoughts on how we should manage our wiki service going forwards.
Thank you all.
Best Regards, Martin Owens Website Administrator Hat
Developer Access Program for Intel Xeon Phi Processors Access to Intel Xeon Phi processor-based developer platforms. With one year of Intel Parallel Studio XE. Training and support from Colfax. Order your platform today. http://sdm.link/xeonphi _______________________________________________ Inkscape-devel mailing list Inkscape-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/inkscape-devel
Hi all,
from a user / author point of view I'd say MediaWiki is the far better choice than what GitHub has to offer MediaWiki is more intuitive to use, has much more features is extensible and I'd also think of it as more future-proof.
I don't know what GitLab has to offer so i can't really comment on that, but I assume it's at best equivalent to GitHub? The fact that a quick web search did not turn up something useful about it is not a good sign either.
From an administrative point of view things look differently of course. I certainly wouldn't want to keep a MediaWiki server running myself and if we don't have the resources there's not much of a question here. In the worst case I guess we could make do with a simple Markdown-Wiki but it would be a step back and I'm pretty sure we'd have to put some effort into the conversion and strip out some parts that are not supported (e.g. templates).
Last but not least there's a visibility argument: I have he impression GitHub Wikis tend to be overlooked, do seldom turn up in Google search results and do not offer good searching capabilities themselves. They also do not seem to invite users to contribute themselves (all I saw so far were Wikis maintained mainly by developers themselves with little input from the community), so in conclusion I'd clearly favour a MediaWiki-based solution.
Regards, Eduard
Am 10.01.2017 um 21:32 schrieb Martin Owens:
Dear developers and wiki enthusiasts,
Our current wiki hosted on wiki.inkscape.org is doing ok, but is running on an old machine that the hosting provider OSUOSL would like to retire if at all possible.
Since we are moving to Git*b, this is an opportunity to also move the wiki to that service. This decreases our system-admin burden and the resources we ask from osuosl.
It would also say that our wiki is more of a developer/contributor focused effort, leaving user content to the website. I expect things like hackfest planning and other plumbing to continue to use a wiki system.
The process of moving it would entail waiting until our code is on git*b and then convert each of the existing pages from MediaWiki syntax to Markdown syntax.
A script such as this https://bitbucket.org/wikier/mw2md could be used, but testing would be needed to see what kind of output we got.
For all people involved in using and editing the wiki, I'd like your thoughts on how we should manage our wiki service going forwards.
Thank you all.
Best Regards, Martin Owens Website Administrator Hat
Developer Access Program for Intel Xeon Phi Processors Access to Intel Xeon Phi processor-based developer platforms. With one year of Intel Parallel Studio XE. Training and support from Colfax. Order your platform today. http://sdm.link/xeonphi _______________________________________________ Inkscape-devel mailing list Inkscape-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/inkscape-devel
I stand corrected!
I assumed there would be a search function on GitHub Wikis - there appears not to be, which is a show-stopper for me at least.
Also, googling quite a bit on GitLab wikis didn't reveal anything either - not very promising.
[Side not: Features-wise I think MarkDown is enough no? It's got links, lists, images, tables, code formatting, headers. What else does the Inkscape wiki use?]
On 10 January 2017 at 22:18, Eduard Braun <Eduard.Braun2@...173...> wrote:
Hi all,
from a user / author point of view I'd say MediaWiki is the far better choice than what GitHub has to offer MediaWiki is more intuitive to use, has much more features is extensible and I'd also think of it as more future-proof.
I don't know what GitLab has to offer so i can't really comment on that, but I assume it's at best equivalent to GitHub? The fact that a quick web search did not turn up something useful about it is not a good sign either.
From an administrative point of view things look differently of course. I certainly wouldn't want to keep a MediaWiki server running myself and if we don't have the resources there's not much of a question here. In the worst case I guess we could make do with a simple Markdown-Wiki but it would be a step back and I'm pretty sure we'd have to put some effort into the conversion and strip out some parts that are not supported (e.g. templates).
Last but not least there's a visibility argument: I have he impression GitHub Wikis tend to be overlooked, do seldom turn up in Google search results and do not offer good searching capabilities themselves. They also do not seem to invite users to contribute themselves (all I saw so far were Wikis maintained mainly by developers themselves with little input from the community), so in conclusion I'd clearly favour a MediaWiki-based solution.
Regards, Eduard
Am 10.01.2017 um 21:32 schrieb Martin Owens:
Dear developers and wiki enthusiasts,
Our current wiki hosted on wiki.inkscape.org is doing ok, but is running on an old machine that the hosting provider OSUOSL would like to retire if at all possible.
Since we are moving to Git*b, this is an opportunity to also move the wiki to that service. This decreases our system-admin burden and the resources we ask from osuosl.
It would also say that our wiki is more of a developer/contributor focused effort, leaving user content to the website. I expect things like hackfest planning and other plumbing to continue to use a wiki system.
The process of moving it would entail waiting until our code is on git*b and then convert each of the existing pages from MediaWiki syntax to Markdown syntax.
A script such as this https://bitbucket.org/wikier/mw2md could be used, but testing would be needed to see what kind of output we got.
For all people involved in using and editing the wiki, I'd like your thoughts on how we should manage our wiki service going forwards.
Thank you all.
Best Regards, Martin Owens Website Administrator Hat
Developer Access Program for Intel Xeon Phi Processors Access to Intel Xeon Phi processor-based developer platforms. With one year of Intel Parallel Studio XE. Training and support from Colfax. Order your platform today. http://sdm.link/xeonphi _______________________________________________ Inkscape-devel mailing list Inkscape-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/inkscape-devel
Developer Access Program for Intel Xeon Phi Processors Access to Intel Xeon Phi processor-based developer platforms. With one year of Intel Parallel Studio XE. Training and support from Colfax. Order your platform today. http://sdm.link/xeonphi _______________________________________________ Inkscape-devel mailing list Inkscape-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/inkscape-devel
Am 10.01.2017 um 22:28 schrieb Olof Bjarnason:
[Side not: Features-wise I think MarkDown is enough no? It's got links, lists, images, tables, code formatting, headers. What else does the Inkscape wiki use?]
Well, you're right that we use the features that MediaWiki offers out-of-the-box rather sparsely right now, but in my opinion we should actually aim at changing that rather than to cut back on features.
Even now I can think quickly think of quite a list of things that would be missing from a Git*b Wiki:
* Image uploads (as far as i can see you have to upload the files elsewhere first, e.g. in a repository) * Templates * Categories * Redirects * Even fundamental styling/layouting would be hard to impossible (for beginners: try to re-create our main page [1] or our latest release notes [2]) * Useful things like Namespaces (including user pages) / Subpages * Useful tools like they can be found on [3] * Watchlists and the like (e.g. [4] which is immensely useful)
An probably a lot more I'm forgetting right now...
As I said before: We possibly could make do without all that, but if there's any chance to stick with MediaWiki that would be my obvious choice.
[1] http://wiki.inkscape.org/wiki/index.php/Inkscape [2] http://wiki.inkscape.org/wiki/index.php/Release_notes/0.92 [3] http://wiki.inkscape.org/wiki/index.php/Special:SpecialPages [4] http://wiki.inkscape.org/wiki/index.php/Special:RecentChanges
Am 10.01.2017 um 23:29 schrieb Eduard Braun:
Am 10.01.2017 um 22:28 schrieb Olof Bjarnason:
[Side not: Features-wise I think MarkDown is enough no? It's got links, lists, images, tables, code formatting, headers. What else does the Inkscape wiki use?]
Well, you're right that we use the features that MediaWiki offers out-of-the-box rather sparsely right now, but in my opinion we should actually aim at changing that rather than to cut back on features.
Even now I can think quickly think of quite a list of things that would be missing from a Git*b Wiki:
- Image uploads (as far as i can see you have to upload the files elsewhere first, e.g. in a repository)
- Those actually work well on gitlab. I've been checking out their functionality yesterday (even SVG works directly! Even in avatars!).
What is cumbersome there currently is inserting headers... Autocompletion gets in the way, as soon as you type #, you get suggestions for bug report links, and when you then hit space, they are inserted...
See also https://gitlab.com/help/user/markdown
- Templates
- Categories
- Redirects
- Even fundamental styling/layouting would be hard to impossible (for beginners: try to re-create our main page [1] or our latest release notes [2])
- Style attributes seem to be removed on gitlab. Whitelist of html elements and attributes for the interested: http://www.rubydoc.info/gems/html-pipeline/1.11.0/HTML/Pipeline/Sanitization... (+ span element)
"align" and "width/height" are supposed to work.
- Useful things like Namespaces (including user pages) / Subpages
- Useful tools like they can be found on [3]
- Watchlists and the like (e.g. [4] which is immensely useful)
An probably a lot more I'm forgetting right now...
As I said before: We possibly could make do without all that, but if there's any chance to stick with MediaWiki that would be my obvious choice.
- I agree with Eduard on all the other points. Especially the 'Recent changes' page is extremely useful, e.g. if you're translating a document. If there's no way to know if there has been an update, it's hard to update a translation on time. I don't think we would have any German or French release notes, and the release notes for 0.92 wouldn't be as complete as they are now (those are currently especially important, because we don't have a manual where developers would document features), if we'd have worked with the kind of wiki git*b offer.
Losing the mediawiki with its notification functionality, and the ability to compare different revisions via web interface (not just a single revision), would mean to lose an important source of information for me (not just for translations, but also for being able to help users).
(btw. what will happen with the idea of the forum living on the Wiki machine if that machine is decommissioned? Do we have any alternatives? Any news from OSUOSL?)
Maren
[1] http://wiki.inkscape.org/wiki/index.php/Inkscape [2] http://wiki.inkscape.org/wiki/index.php/Release_notes/0.92 [3] http://wiki.inkscape.org/wiki/index.php/Special:SpecialPages [4] http://wiki.inkscape.org/wiki/index.php/Special:RecentChanges
On Wed, 2017-01-11 at 00:35 +0100, Maren Hachmann wrote:
(btw. what will happen with the idea of the forum living on the Wiki machine if that machine is decommissioned? Do we have any alternatives? Any news from OSUOSL?)
The only thing I've heard is the message we got many weeks ago. They'd really really like to move us away from a custom Gentoo box and towards a managed system, things like the Forum, Wiki and Planet are natural modules for such a managed system.
If we install a forum on the wiki server, we'd be doing it on our own. It's something we could do, it's available to us, but a more conservative look says we probably shouldn't be.
But we can continue to dialog with them about the services we have with them. I'll be honest, if decommissioning the wiki machine helps us with our admin and makes osuosl happy enough to help us more with forums and websites, I'd like to be able to make them happy with us.
Best Regards, Martin Owens
Am 11.01.2017 um 01:31 schrieb Martin Owens:
On Wed, 2017-01-11 at 00:35 +0100, Maren Hachmann wrote:
(btw. what will happen with the idea of the forum living on the Wiki machine if that machine is decommissioned? Do we have any alternatives? Any news from OSUOSL?)
The only thing I've heard is the message we got many weeks ago. They'd really really like to move us away from a custom Gentoo box and towards a managed system, things like the Forum, Wiki and Planet are natural modules for such a managed system.
- I'd love to see that (but didn't understand that this was what they meant). Planet isn't updating for almost a year now, some types of Wiki mails go into mail nirvana, mediawiki software is a version that doesn't get any security updates any more, forum discussion could be shortened by lengths if we could just accept what they offer.
Maren
If we install a forum on the wiki server, we'd be doing it on our own. It's something we could do, it's available to us, but a more conservative look says we probably shouldn't be.
But we can continue to dialog with them about the services we have with them. I'll be honest, if decommissioning the wiki machine helps us with our admin and makes osuosl happy enough to help us more with forums and websites, I'd like to be able to make them happy with us.
Best Regards, Martin Owens
I didn't realize we were thinking of having the forum on the wiki machine. Not unless OSUOSL was going to give us more space there. But it seems like that would be less than ideal anyway, unless my understanding that we don't have root access there, is wrong. It was an option originally, but I thought we had eliminated it as an option, and moved on.
I thought OSUOSL was going to set up a whole new kind of system for us. I haven't understood the details about that, because it's over my head. But to my understanding, we're thinking we'll get a new server.
That's assuming their answer to our request is positive. To my understanding, and to my knowledge, they haven't said 'yes' to a forum, and they could still say 'no'. Yes, they did say what they were thinking of doing (something different than what we have now). But as time keeps marching along, and all we hear are crickets, I have to wonder.
All best, brynn
-----Original Message----- From: Martin Owens Sent: Tuesday, January 10, 2017 5:31 PM To: Maren Hachmann ; inkscape-devel@lists.sourceforge.net Subject: Re: [Inkscape-devel] Forum, was: Move Wiki
On Wed, 2017-01-11 at 00:35 +0100, Maren Hachmann wrote:
(btw. what will happen with the idea of the forum living on the Wiki machine if that machine is decommissioned? Do we have any alternatives? Any news from OSUOSL?)
The only thing I've heard is the message we got many weeks ago. They'd really really like to move us away from a custom Gentoo box and towards a managed system, things like the Forum, Wiki and Planet are natural modules for such a managed system.
If we install a forum on the wiki server, we'd be doing it on our own. It's something we could do, it's available to us, but a more conservative look says we probably shouldn't be.
But we can continue to dialog with them about the services we have with them. I'll be honest, if decommissioning the wiki machine helps us with our admin and makes osuosl happy enough to help us more with forums and websites, I'd like to be able to make them happy with us.
Best Regards, Martin Owens
------------------------------------------------------------------------------ Developer Access Program for Intel Xeon Phi Processors Access to Intel Xeon Phi processor-based developer platforms. With one year of Intel Parallel Studio XE. Training and support from Colfax. Order your platform today. http://sdm.link/xeonphi _______________________________________________ Inkscape-devel mailing list Inkscape-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/inkscape-devel
Thanks Eduard and Olof for your quick replies.
Both GitHub and GitLab wikis are markdown based git repositories based on the Ruby GEM project "Gollum" (extended in their own ways).
This system does make it easier for us to port media-wiki as "all we have to do"[1] is drum up a git repository that records all the edits by the right people at the rights rime and we get to keep our media wiki history.
GitLab as hosted by gitlab.org provides a search for the wiki attached to a project. It's the same box as a search in the project, but searches the wiki when in wiki mode.
Let's take these features one at a time using this page: https://docs.g itlab.com/ee/user/markdown.html
Image uploads (as far as i can see you have to upload the files elsewhere first, e.g. in a repository)
There's an "attach a file" link at the bottom right hand side of the editor box. All files, images, videos etc are held in the same repository as the wiki's markdown or md files.
Templates
A commit 3 days ago: https://gitlab.com/gitlab-org/gitlab-ce/merge_requ ests/8487 We'd have to wait for it, but it seems actively filling in what's missing.
Categories
More than a directory categorisation? Is this an added meta- categorisation required?
Redirects
Not supported. Not sure if it could be regarding security etc.
Even fundamental styling/layouting would be hard to impossible (for beginners: try to re-create our main page [1] or our latest release notes [2])
I question the need for this complex layout, it made sense back when the website was an uneditable static site not updated in years. But it's now an uneditable dynamic site updated in weeks. Which is completely different and I don't think we need to be as complex with developer/contributor information.
Useful things like Namespaces (including user pages) / Subpages
For user pages, a person can make as many wiki's for themselves as the want in their own gitlab user account, no need for inkscape's project wiki to be used for that. Directories are available for subpages.
Useful tools like they can be found on [3]
Not everything will be available. Somethings might be though.
Watchlists and the like (e.g. [4] which is immensely useful)
Since it's a git repository, a user can watch for changes and see recent changes just like any repository.
There are some advantages too, such as dynamic checkboxes for task lists (immensely useful for what we do with the wiki), inline diffs, code syntax highlighting, linking to issues, code commits, users, milestone etc. Linking to specific files in the main repository.
Basically some useful code/project integration features which we'd never have on media-wiki.
Also it'd be fun, but not really that hard, to have the website keep a copy of the wiki repository and to index it every so often. Imagine being able to run a search on the website and wiki at the same time. Oh the fun we could have! ;-)
Best Regards, Martin Owens
[1] All we have to do is not in any way intended to make you believe it would be easy, qualitative or fast. But it could be.
Am 11.01.2017 um 01:13 schrieb Martin Owens:
Thanks Eduard and Olof for your quick replies.
Templates
A commit 3 days ago: https://gitlab.com/gitlab-org/gitlab-ce/merge_requ ests/8487 We'd have to wait for it, but it seems actively filling in what's missing.
- This is nice, but it's something completely different from the Wiki templates. The templates we have are rather snippets, that auto-fill with data from the page. They are inserted *into* the page, not *as* page. Like the one that links to different translations, or the one that you insert when a page is outdated, etc. They are used extensively currently.
Categories
More than a directory categorisation? Is this an added meta- categorisation required?
- It is useful to organize the large Wiki we have.
Redirects
Not supported. Not sure if it could be regarding security etc.
- Just wondering: we'd be causing dead links left and right on the internet when we kill the current subdomain...
Even fundamental styling/layouting would be hard to impossible (for beginners: try to re-create our main page [1] or our latest release notes [2])
I question the need for this complex layout, it made sense back when the website was an uneditable static site not updated in years. But it's now an uneditable dynamic site updated in weeks. Which is completely different and I don't think we need to be as complex with developer/contributor information.
- This is something I also care less about.
Useful things like Namespaces (including user pages) / Subpages
For user pages, a person can make as many wiki's for themselves as the want in their own gitlab user account, no need for inkscape's project wiki to be used for that. Directories are available for subpages.
- User pages are less important, I agree. The page hierarchy, however, does not appear to be reflected in the menu on the right at gitlab, it just lists all of them, as far as I could see (but maybe my mini-wiki was just too small?).
Watchlists and the like (e.g. [4] which is immensely useful)
Since it's a git repository, a user can watch for changes and see recent changes just like any repository.
- I couldn't find an option that one can check in the interface, to get email notifications. How would I go about creating something like that? (could even be a script)?
Is there a graphical diff available somewhere for the Wiki git? (I found one for single pages, with single commit listings, but no way to summarize a couple of those, or see a list of changes for the full Wiki online).
These two things are the most important functionalities for me.
Btw. is it possible to revert any Wiki changes (through the interface)?
There are some advantages too, such as dynamic checkboxes for task lists (immensely useful for what we do with the wiki),
- Yes, those are nice.
inline diffs, code syntax highlighting, linking to issues, code commits, users, milestone etc. Linking to specific files in the main repository.
- linking to gitlab issues is probably not relevant for us...
Basically some useful code/project integration features which we'd never have on media-wiki.
- Normal links do work, too. I'd prefer if OSUOSL could host a full-featured Wiki for us...
Maren
Hello Martin,
As already said, my focus will go to searchability and keywords.
Regards, Adib.
Martin Owens <doctormo@...400...> schrieb am Mi., 11. Jan. 2017 um 01:15:
Thanks Eduard and Olof for your quick replies.
Both GitHub and GitLab wikis are markdown based git repositories based
on the Ruby GEM project "Gollum" (extended in their own ways).
This system does make it easier for us to port media-wiki as "all we
have to do"[1] is drum up a git repository that records all the edits
by the right people at the rights rime and we get to keep our media
wiki history.
GitLab as hosted by gitlab.org provides a search for the wiki attached
to a project. It's the same box as a search in the project, but
searches the wiki when in wiki mode.
Let's take these features one at a time using this page: https://docs.g
itlab.com/ee/user/markdown.html
Image uploads (as far as i can see you have to upload the files
elsewhere first, e.g. in a repository)
There's an "attach a file" link at the bottom right hand side of the
editor box. All files, images, videos etc are held in the same
repository as the wiki's markdown or md files.
Templates
A commit 3 days ago: https://gitlab.com/gitlab-org/gitlab-ce/merge_requ
ests/8487 We'd have to wait for it, but it seems actively filling in
what's missing.
Categories
More than a directory categorisation? Is this an added meta-
categorisation required?
Redirects
Not supported. Not sure if it could be regarding security etc.
Even fundamental styling/layouting would be hard to impossible (for
beginners: try to re-create our main page [1] or our latest release
notes [2])
I question the need for this complex layout, it made sense back when
the website was an uneditable static site not updated in years. But
it's now an uneditable dynamic site updated in weeks. Which is
completely different and I don't think we need to be as complex with
developer/contributor information.
Useful things like Namespaces (including user pages) / Subpages
For user pages, a person can make as many wiki's for themselves as the
want in their own gitlab user account, no need for inkscape's project
wiki to be used for that. Directories are available for subpages.
Useful tools like they can be found on [3]
Not everything will be available. Somethings might be though.
Watchlists and the like (e.g. [4] which is immensely useful)
Since it's a git repository, a user can watch for changes and see
recent changes just like any repository.
There are some advantages too, such as dynamic checkboxes for task
lists (immensely useful for what we do with the wiki), inline diffs,
code syntax highlighting, linking to issues, code commits, users,
milestone etc. Linking to specific files in the main repository.
Basically some useful code/project integration features which we'd
never have on media-wiki.
Also it'd be fun, but not really that hard, to have the website keep a
copy of the wiki repository and to index it every so often. Imagine
being able to run a search on the website and wiki at the same time. Oh
the fun we could have! ;-)
Best Regards, Martin Owens
[1] All we have to do is not in any way intended to make you believe it
would be easy, qualitative or fast. But it could be.
Developer Access Program for Intel Xeon Phi Processors
Access to Intel Xeon Phi processor-based developer platforms.
With one year of Intel Parallel Studio XE.
Training and support from Colfax.
Order your platform today. http://sdm.link/xeonphi
Inkscape-devel mailing list
Inkscape-devel@lists.sourceforge.net
On Tue, Jan 10, 2017 at 03:32:23PM -0500, Martin Owens wrote:
Since we are moving to Git*b, this is an opportunity to also move the wiki to that service. This decreases our system-admin burden and the resources we ask from osuosl.
I'd like to offer a proposal for a path forward here, merging ideas and concerns everyone's put in:
#0 - No change to the current wiki until Inkscape's codebase is migrated to git. So, probably no change for 2+ months. Thus, people considering using the wiki for things right now, should proceed with doing those things.
#1 - Application documentation and references 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, current and upcoming release notes, 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.
#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. None of this should be translated.
#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 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. 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.
Please tell me what you think of this plan. If it looks ok, I'll repost as a proper RFC so everyone can have a chance to poke holes at it before it's engaged.
Thanks, Bryce
Hi Bryce,
I like this plan, it sorts out a lot of the multitudes we have in the wiki satisfactorly.
...
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. 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.
It could also be a inkscape-community Git*b project with really lax rules for committing. There we get to lean on Git*b for spam control and user account management and can also elevate users to other permissions if they'd like to edit other things.
Please tell me what you think of this plan. If it looks ok, I'll repost as a proper RFC so everyone can have a chance to poke holes at it before it's engaged.
I'm on board.
Martin,
Makes my contributing easier --- I got a wiki account, but never remember my password --- it's stored in my e-mail archive on my other computer at work.
Looking forward to it!
William
On Mon, Jan 16, 2017 at 11:22 AM, Martin Owens <doctormo@...400...> wrote:
Hi Bryce,
I like this plan, it sorts out a lot of the multitudes we have in the wiki satisfactorly.
...
This could be an updated MediaWiki like we currently have,however I'd like to see thought given to alternativesolutions, such as a Django wiki plugin that allows tighter integration with the website, or even using an externally maintained wiki service. 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.
It could also be a inkscape-community Git*b project with really lax rules for committing. There we get to lean on Git*b for spam control and user account management and can also elevate users to other permissions if they'd like to edit other things.
Please tell me what you think of this plan. If it looks ok, I'll repost as a proper RFC so everyone can have a chance to poke holes at it before it's engaged.
I'm on board.
Martin,
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
Hi Bryce,
so it seems we'd need these places for collaborative editing (except code):
a) a community planning/organizing place b) a developer planning/organizing place c) a space for presentation d) a place for official user documentation e) a place for official developer documentation f) an archive
After using your approach, we would have (numbers don't correspond to yours):
1. some other kind of wiki for user discussion/user idea development 2. git*b wiki for devel discussion 3. website 4. directory in inkscape source code for user docs 5. directory in inkscape source code for devel docs 6. old wiki for archiving 7. manual(s) outside of project, currently missing in project 8. inkscape-docs project
I'd suggest a (partially) different organization:
for a) A git*b community wiki sounds fine to me. I assume we would mostly use it for board meetings organization and other organizational planning. At least that's what happens on the Wiki atm.
for b) A git*b developer wiki sounds good for this, blueprints etc. can be fleshed out there (although I must say that the 'issues' at git*b aren't a bad way to have iterative discussions, with checklists and lots of linking, either).
for c) Website, I agree. I wouldn't use this for drafting stuff, like the release notes, though. That could be done in either e) or b) or even a). In my experience, every new website editor breaks the site at least once, and it's also awfully slow. I doubt devs will enjoy drafting release notes there.
Putting them on the page later in a one-off action is fine, but may not be needed: this is already part of the releases app and doesn't require any additional pages - could be fleshed out, though, to allow for integrated images. Example of current status: https://inkscape.org/en/release/0.48/- it does support html and translations (if you wonder why the ones for 0.92 are not formatted as well: I just copy-pasted the notes for 0.92 from your tarball's description, no time for re-formatting).
for d) This is the point where I disagree. I wouldn't put that into the Inkscape source repo. I find it's hidden there from user view and user collaboration. I'd rather see it combined with the manual efforts and the inkscape-docs repo to create some sort of coherent documentation. In the beginning, I presume, it would consist of a lot of different bits from different sources, perhaps only held together by a common table of contents. This could then be included with Inkscape, made available from the website, sold, etc.
No idea of the best format for this, though, as it's supposed to be translatable, and it would be good if it could be exported into different formats, and needs to be version-controlled. How do other projects organize creation of their user documentation? What tools do they use? I could live with git and markdown, but there are probably better ways that make it easy to contribute and have better support for translation.
for e) Will it encourage devs to update dev documentation if it's within the Inkscape source tree? Where would coders want to keep their documentation, and where will they see and update it? On the current Wiki, it's rarely updated. On the website, it's rarely updated. Don't know about how it would be if it's in the source.
for f) How can that be done? A static site? (with all subpages, history etc. that would be huge... unless we don't copy edit histories and other pages along with it.) Put Wiki into non-editable mode? We'd still need to keep it around and host it, and it will break some day.
Just FYI:
Inkscape currently has about 730 Wiki pages (most of which would end up in the archive, because they're outdated, but historically interesting, I think).
The Wiki cleanup effort and the documentation effort that seems to be related, are currently road-mapped for version 1.0. Starting early can't hurt, of course - if I understand this correctly, there is some time pressure?
Maren
Am 16.01.2017 um 09:33 schrieb Bryce Harrington:
On Tue, Jan 10, 2017 at 03:32:23PM -0500, Martin Owens wrote:
Since we are moving to Git*b, this is an opportunity to also move the wiki to that service. This decreases our system-admin burden and the resources we ask from osuosl.
I'd like to offer a proposal for a path forward here, merging ideas and concerns everyone's put in:
#0 - No change to the current wiki until Inkscape's codebase is migrated to git. So, probably no change for 2+ months. Thus, people considering using the wiki for things right now, should proceed with doing those things.
#1 - Application documentation and references 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, current and upcoming release notes, 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.
#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. None of this should be translated.
#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 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. 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.Please tell me what you think of this plan. If it looks ok, I'll repost as a proper RFC so everyone can have a chance to poke holes at it before it's engaged.
Thanks, Bryce
Developer Access Program for Intel Xeon Phi Processors Access to Intel Xeon Phi processor-based developer platforms. With one year of Intel Parallel Studio XE. Training and support from Colfax. Order your platform today. http://sdm.link/xeonphi _______________________________________________ Inkscape-devel mailing list Inkscape-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/inkscape-devel
On Tue, Jan 17, 2017 at 12:32:34AM +0100, Maren Hachmann wrote:
Hi Bryce,
so it seems we'd need these places for collaborative editing (except code):
a) a community planning/organizing place b) a developer planning/organizing place c) a space for presentation d) a place for official user documentation e) a place for official developer documentation f) an archive
After using your approach, we would have (numbers don't correspond to yours):
- some other kind of wiki for user discussion/user idea development
- git*b wiki for devel discussion
- website
- directory in inkscape source code for user docs
- directory in inkscape source code for devel docs
- old wiki for archiving
- manual(s) outside of project, currently missing in project
- inkscape-docs project
Thanks for reviewing my proposal, and that looks like a decent summary of the suggested divisions.
I'd suggest a (partially) different organization:
for a) A git*b community wiki sounds fine to me. I assume we would mostly use it for board meetings organization and other organizational planning. At least that's what happens on the Wiki atm.
Yes, although my hope is it would be broader into the community. I know we have organized community activities around Inkscape but outside the actual development community, and think it would benefit us all to create a space they can also use to organize and share information.
Our current wiki has been relied on heavily for many "official" purposes so hasn't really been suitable for wider community needs. So my hope is this new wiki would be much less critical for project development and planning, and could be more available for the wider community.
for b) A git*b developer wiki sounds good for this, blueprints etc. can be fleshed out there (although I must say that the 'issues' at git*b aren't a bad way to have iterative discussions, with checklists and lots of linking, either).
Ok. Good point we should remain open to that.
for c) Website, I agree. I wouldn't use this for drafting stuff, like the release notes, though. That could be done in either e) or b) or even a). In my experience, every new website editor breaks the site at least once, and it's also awfully slow. I doubt devs will enjoy drafting release notes there.
Good point. I notice that we need more formatting control in the release notes than a typical wiki might have. But then again, the release notes are also more than a web page. I lumped them in with the web site, but you're right they may deserve special handling - and you're right the releases app plays a heavy role with them. They are perhaps the most important content item we create, so may need to be their own "thing". I'll update the plan accordingly.
for d) This is the point where I disagree. I wouldn't put that into the Inkscape source repo. I find it's hidden there from user view and user collaboration. I'd rather see it combined with the manual efforts and the inkscape-docs repo to create some sort of coherent documentation. In the beginning, I presume, it would consist of a lot of different bits from different sources, perhaps only held together by a common table of contents. This could then be included with Inkscape, made available from the website, sold, etc.
No idea of the best format for this, though, as it's supposed to be translatable, and it would be good if it could be exported into different formats, and needs to be version-controlled. How do other projects organize creation of their user documentation? What tools do they use? I could live with git and markdown, but there are probably better ways that make it easy to contribute and have better support for translation.
There is no one way that other projects do it, obviously. However, many projects I've been involved with use git for maintaining their user documentation, and typically generate it much like the software itself is built, using make and some tool chain to generate HTML, PDF, and other formats. There's a wide diversity of formats and tools used for authoring the content - docbook, markdown, latex, publican, even HTML. The systems generally also incorporate provisions for storing and tracking translations of the source files too. For Inkscape, I would probably study the toolchain we're using to generate the tutorials as one possibility; being able to generate our user documentation into SVG might enable us to achieve more than we could with other formats...
Some projects I've been involved with (e.g. Wayland and Cairo), the user docs are generated and deployed to the website as part of the regular release process.
I definitely would expect some sort of automatic publishing process, because you're right that without that the docs would be hidden from users. With publishing, our 'make dist' would also make PDFs and HTMLs of all the user docs and see that they're distributed to and published online as needed.
A long term hope of mine is to see our core inkscape repo be split up into multiple repos that can be better maintained discretely yet in sync. I would definitely want to see some synergy achieved by merging user docs, manual efforts, and so on with inkscape-docs. Whether this would be a single unified document, that could be distributed, published online, sold, etc. or would rather be a loose collection, I don't know, but regardless I think our current wiki is not the right kind of house for them.
for e) Will it encourage devs to update dev documentation if it's within the Inkscape source tree? Where would coders want to keep their documentation, and where will they see and update it? On the current Wiki, it's rarely updated. On the website, it's rarely updated. Don't know about how it would be if it's in the source.
Frankly, dev documentation is rarely updated, regardless of where it's placed. I think devs are slightly more likely to update it in git than elsewhere, but honestly it really depends. Certainly having it in git doesn't make it *less* accessible to devs, and that way it frees up the wiki for more useful purposes.
for f) How can that be done? A static site? (with all subpages, history etc. that would be huge... unless we don't copy edit histories and other pages along with it.) Put Wiki into non-editable mode? We'd still need to keep it around and host it, and it will break some day.
As long as a backup of the current site is made that preserves the change history, I think a static site just showing the current page state would be more than sufficient. This would be non-editable, and could be flattened to plain HTML to eliminate the need for any code to actually be executed for page views. Ideally it should permit existing links to continue to resolve properly with minimial need for redirects.
But I want to be deliberately hand-wavy here, since there are probably a few ways to skin this cat. For example, browsing of revision histories might not be that difficult, and might have some utilization. The main point is to mothball them in a way that effectively eliminates any administration or maintenance work needed while keeping them available for us to reference as needed.
Bryce
Am Dienstag, 17. Januar 2017, 00:32:34 CET schrieb Maren Hachmann:
[...]
for e) Will it encourage devs to update dev documentation if it's within the Inkscape source tree? Where would coders want to keep their documentation, and where will they see and update it? On the current Wiki, it's rarely updated. On the website, it's rarely updated. Don't know about how it would be if it's in the source.
Just a small data point from someone who looks into different open source programs' sources every now and then: If the dev docs are not coming along with the sources then they might as well not exist. Having them in a wiki is great for regular contributors who know the structure of a project, but someone using the program, seeing a bug and being eager to fix it won't know where to look for those. Besides easier discoverability there is also the benefit of having the documentation available when not being online, so hacking while commuting by train is easier.
[...]
Maren
Tobias
[...]
Am 17.01.2017 um 10:45 schrieb Tobias Ellinghaus:
Am Dienstag, 17. Januar 2017, 00:32:34 CET schrieb Maren Hachmann:
[...]
for e) Will it encourage devs to update dev documentation if it's within the Inkscape source tree? Where would coders want to keep their documentation, and where will they see and update it? On the current Wiki, it's rarely updated. On the website, it's rarely updated. Don't know about how it would be if it's in the source.
Just a small data point from someone who looks into different open source programs' sources every now and then: If the dev docs are not coming along with the sources then they might as well not exist. Having them in a wiki is great for regular contributors who know the structure of a project, but someone using the program, seeing a bug and being eager to fix it won't know where to look for those. Besides easier discoverability there is also the benefit of having the documentation available when not being online, so hacking while commuting by train is easier.
[...]
- Thank you, Tobias! That makes sense.
Maren
participants (9)
-
Bryce Harrington -
brynn -
Eduard Braun -
Maren Hachmann -
Martin Owens -
Olof Bjarnason -
the Adib -
Tobias Ellinghaus -
William Adams