[RFC] Wiki replacement plan

classic Classic list List threaded Threaded
10 messages Options
Reply | Threaded
Open this post in threaded view
|

[RFC] Wiki replacement plan

Bryce Harrington-3
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/inkscape-devel
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Wiki replacement plan

Brynn
> #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: [hidden email]
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/inkscape-devel 


------------------------------------------------------------------------------
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/inkscape-devel
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Wiki replacement plan

Eduard Braun
In reply to this post by Bryce Harrington-3
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

------------------------------------------------------------------------------
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/inkscape-devel
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Wiki replacement plan

Bryce Harrington-3
In reply to this post by Brynn
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: [hidden email]
> 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
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/inkscape-devel

------------------------------------------------------------------------------
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/inkscape-devel
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Wiki replacement plan

Martin Owens-2
In reply to this post by Eduard Braun
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

------------------------------------------------------------------------------
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/inkscape-devel
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Wiki replacement plan

Brynn
In reply to this post by Bryce Harrington-3
> 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: [hidden email]
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


------------------------------------------------------------------------------
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/inkscape-devel
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Wiki replacement plan

Maren Hachmann
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

------------------------------------------------------------------------------
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/inkscape-devel
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Wiki replacement plan

Eduard Braun
In reply to this post by Martin Owens-2
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 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.
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

------------------------------------------------------------------------------
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/inkscape-devel
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Wiki replacement plan

Maren Hachmann
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

------------------------------------------------------------------------------
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/inkscape-devel
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Wiki replacement plan

Martin Owens-2
In reply to this post by Eduard Braun
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

------------------------------------------------------------------------------
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/inkscape-devel