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 < th.v.d.gronde@...528...> wrote:
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.
Absolutely.
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 editor.)
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 /community/something)
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@...2495...>
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, etc)
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 HTML content
(But please, it's reStructuredText, not RestructuredText)
Anybody else loves sphinx? :)
Yay!
-----
2010/12/16 Josh Andler <scislac@...400...>
2010/12/15 Krzysztof Kosiński <tweenk.pl@...400...>:
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@...18...> 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@...400...
wrote:
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.
Regards,
Chris Morgan.