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