Here's one big long response to most of the contents of this thread. Hope
you can work out what I mean; I wrote the responses to the first one
yesterday and the rest today.
On Wed, Dec 15, 2010 at 8:52 PM, Jasper van de Gronde <
> We indeed have documentation that does not need to be on a wiki (and a
> lot of it isn't on the wiki), and you're completely right that for a lot
> of documentation the wiki simply isn't the right place.
> However, that's not all that's on the Wiki. It also provides a place for
> people to write proposals, discuss (in a more structured manner than on
> the mailing list) and keep track of things. And it has a relatively low
> barrier for entry, which is quite crucial in my opinion.
Whoever said proposals and discussion has to take place in a wiki? There
can easily be other ways of doing that. (The general idea of the wiki
workflow can remain, though. I just mean I think it should feel more like
part of the main website in general, though I'd have to see how it ends up
feeling and reacting; it may not work well. development/proposals/* or
something like that.)
I'm not saying that it would be impossible to live without the Wiki, but
> it's not just an accumulation of documents and definitely does serve a
> purpose. It could be improved, and I agree that some things may not
> belong there, but eradicating it altogether should not be done lightly.
Definitely; I'm suggesting that a significant quantity of what's there is
either moved into developer region or put in the main part of the site.
Also, if we were to move a lot of things away from the Wiki then we
> really should think about making it easier to update the website. I
> wouldn't have a clue how it's done.
BTW, if you have documents that can be viewed on-line, in some easily
editable syntax and community editable through BZR, what's the
> difference with a Wiki? (Except that you can't easily link between
> documents in BZR, would need to agree on a file format and that you
> would force anyone wanting to edit a document to install BZR and some
My intent is to keep this backed by the file system and a Bazaar
repository. When people think of this, they seem to think that this implies
that you'll require Bazaar to be installed. *It doesn't need to be that
way.* The website can provide a normal web interface for document editing
which modifies and commits content in the backend. (Google Code's wiki
system works that way and one or two CMSes are now doing that.)
Concerning the format, clearly the format used must be decided upon; my
personal recommendation for this is using reStructuredText; it's clean, neat
and easily understandable. There are then two link styles that can be used;
* Wiki style "page title is in the URL". This is not my preference; I like
my slugs to be brief and concise.
* Use concise slugs; /wiki/communities (rather than
/wiki/International_and_Local_Communitites (concerning that page on the
existing wiki - what exactly does "local" mean!?). Just like the rest of a
site always is. (Or better still, integrated into the main website as
Internal linking can be done easily.
I just went and looked at the front page of the wiki. In my opinion, with
the website easily editable in a reasonable format (i.e. not HTML as it
currently is), and with the site restructuring we're planning on doing, *none
of it belongs in a wiki.* "About Inkscape"? What was that doing there in
the first place? "User Documentation"? That all fits in /learn
----- (The portion of the email above was written before reading further in
the conversation. It now turns out that Néstor likes RST as well!)
2010/12/16 Néstor Díaz Valencia <nestor@...>
> maybe out of the scope of the website refactoring, but can it be that if
> we standarise documentation around reST (RestructuredText) and Sphinx
> http://sphinx.pocoo.org/ we may end up with:
> a- Great browseable code documentation
> b- Nice drafts, discussions wiki (we make a django with sphinx rest
> files backend)
> c- Nice end user documentation including offline consulting (html, pdf,
> And the flow a <-> b <-> c <-> a , or information lifecycle will go smooth.
I was intending to do this not with the developer documentation but with
most of the content on the main website and the hypothetical wiki; those
pages that need to be HTML (e.g. front page, download page) can still be
(But please, it's reStructuredText, not RestructuredText)
Anybody else loves sphinx? :)
2010/12/16 Josh Andler <scislac@...>
> 2010/12/15 Krzysztof Kosiński <tweenk.pl@...>:
> > What is needed is a concerted effort to organize the information
> > available on the wiki, and remove outdated information.
> I absolutely agree. We seem to have lots of people interested in
> replacing the wiki or otherwise showing some form of interest at the
> moment. Energy and enthusiasm is good and we need to tap into it while
> it's there. So really, it seems like the main areas that need to be
> dealt with are some restructuring/reorganizing where it makes sense,
> removing truly deprecated information, updating things that are still
> partially accurate, and what else?
> Do we have any takers for the "overhaul" stuff as opposed to
> rebuilding? I know I will be busy through the holidays, but after that
> could commit about an hour a day to working on some of this.
I think it would be helpful doing this in a decided format in a repository,
rather than in the wiki; really, starting preparing the content migration
before the site is ready. We'll need to pull the content from the wiki
anyway and reformat it. So far we have two liking reStructuredText and no
other suggestions so I'd recommend using that format. (Besides which, it's
a simple and readable enough format that migration is pretty easy.)
On Thu, Dec 16, 2010 at 4:47 AM, Jon Cruz <jon@...> wrote:
> I've been in the situation in the past where we've had a wiki replaced by
> the "just as good" alternative. Problem is... a wiki is also very much about
> the usage and workflow, and even a nicer CMS like Alfresco or such is just
> not the same.
I think we can improve upon it by making it web-editable and text
editor-editable (beyond testing to make sure it works, I know which I'll
use; give me a text editor any day - most people seem to normally write
their text in a decent text editor anyway and just copy it into the
website's textarea when they're done. Keeping it - or at least the
possibility of keeping it - entirely in a text editor and console is a great
improvement in my opinion.)
Smaller bits of information, cross-linking and content evolving over time
> are a few keys.
I'll be taking all of these into consideration; I believe we can do it well.
On Thu, Dec 16, 2010 at 8:02 PM, Hinerangi Courtenay <duckgoesoink@...
> Taking the wikibooks.org example, their information is clearly laid out
> and organized into easily readable sections, with drafts clearly defined as
> such. Making edits is easy and anonymous.
And currently the Inkscape wiki is not anonymously editable. And that is a
feature I *definitely* intend to keep.
The current wiki is difficult to navigate (visually), and how to edit is not
> too obvious (instructions hidden behind WikiSyntax I believe). Getting back
> to the main website is confusing. I would gladly help tidy up wiki
> documentation but don't feel in a position to do so (I use Inkscape daily
> but am just a user - I don't know much about the technicalities of the
> project nor about writing/editing user documentation).
Indeed, the current system is cumbersome and unfriendly. I haven't updated
information on the wiki a number of times because it was just too hard... if
it had been in a repository, I would have; I think I did finally create an
account and have edited one or two pages but I really can't remember well...
my experience with the current wiki is almost entirely negative, really.
> Also, some information may be easier (or more appropriate) to organize on
> the main website (long sections of general information). There is some good
> content but when it's on a wiki it can feel like unstable (therefore
> unreliable) information to a new user.
I agree entirely with this. As noted earlier, I think just about all of the
primary content in the wiki (the stuff linked to from the front page)
belongs on the main site. I imagine the reason it hasn't been there is
because it's just been too hard to do. The old system was very inflexible.
I've run out of emails to comment on!
As is usual in long emails I write, they tend to be significantly
fragmented. Please ask if you don't understand or want me to explain
something further, etc.