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