couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Javier Candeira (JIRA)" <>
Subject [jira] [Commented] (COUCHDB-2350) Finish move of the wiki documentation; clean up references in
Date Thu, 09 Oct 2014 11:23:34 GMT


Javier Candeira commented on COUCHDB-2350:

This is a discussion between dch and myself yesterday:

< kandinski> dch: why are we moving away from the old wiki?
< kandinski> I mean, makes sense to move away from a wiki to a real documentation site
< kandinski> but why from the old wiki to the new wiki? There seems to be a lot of redundant
stuff there already 
<+dch> kandinski: the confluence one is nicer, and people were keen enough to start
moving stuff. 
< kandinski> maybe redundant not the best word for it
<+dch> originally there was only the wiki
<+dch> and then we got the rst format docs 
<+dch> and there was duplication
< kandinski> that I get
<+dch> and IIRC stuff is “retired” from old wiki as it moves into docs or new wiki
<+dch> not really a planned nor coordinated process
< kandinski> it's the second wiki I don't get.
<+dch> coz pretty?
<+dch> or am I missing something.
< kandinski> I'll give you examples
<+dch> I don’t really like any wikis myself. markdown and static sites make me happy.

< kandinski> I'm planning to get assigned this job, so..
< kandinski> well, I think wikis are useful for stuff where many contributors are better
than a few specialists
< kandinski> let's start at the top: 
< kandinski> About CouchDB: Introduction. Should be much shorter. and maybe be an introduction
to the wiki. The introduction to COuchDB is
< kandinski> CouchDB Team: this page has no business being a wiki. This is maintained
by the team in
< kandinski> Official Resources. Same.
< kandinski> Useful links: too generic. There is "libraries and links", there is "books",
there is "other databases using the couchdb replication protocol" 
< kandinski> having a "useful links" page in a wiki is like having a "printed paper"
section in a newspaper
<+dch> lols
< kandinski> "current releases" is also something that has no business being edited
by random CouchDB users, so it should be a part of either or
<+dch> kandinski: you’re totally welcome to fix these up, all of the stuff you mentioned
makes sense.
< kandinski> and "source code" hardly merits a wiki page. It's not like random users
are going to improve on whatever the team has.
< kandinski> Yep, I'm assigning myself paring the new wiki down to a few useful pages.
<+dch> woot
< kandinski> and writing the first draft of "other couch* and *ouchDB" page for the
docs sites
<+dch> a lot of this stuff would fit better in the official docs btw
< kandinski> for the first section, it's either the official docs or nothing
< kandinski> by the way, the wiki has TWO different places to put the "other couch*
and *ouchDB projects"
< kandinski> which is such an important piece of information that should be edited with
care by someone central to the project, btw.
< kandinski> I'm only offering to provide a first draft, a canvas of sorts.
<+dch> having N places to read stuff is not good.
<+dch> this is why I’m not a fan in general of the wiki approach. no curation &
no structure.
< kandinski> Well, wikis are great for the offshoots, and content that is fast moving.
<+dch> that and the daft format.
<+dch> [[links|different]] in every wiki software I ever used
< kandinski> ah, that is a killer too
< kandinski> but /shrug
< kandinski> Ok, this is a biggish job
< kandinski> I'm going to make a spreasheet with four columns
< kandinski> old wiki, new wiki, docs, comments
< kandinski> and request rough consensus before paring things down to one place for
each category of information
<+dch> kandinski: my suggestion is to publish your proposed steps, and just assume lazy
consensus along the way.
< kandinski> yeah, I mean, after this conversation, plus Joan telling me she hated the
wiki too, I have more or less an indication of how far I'm allowed to go on my own
< kandinski> publish plan, and if no oppossition in a day or two, move ahead
<+dch> +1 for that. gfdi .<
< kandinski> dch: I intend to read all the documentation first, and take notes. This
may take me a couple of weeks to a month (of spare time).

> Finish move of the wiki documentation; clean up references in
> ------------------------------------------------------------------------------
>                 Key: COUCHDB-2350
>                 URL:
>             Project: CouchDB
>          Issue Type: Improvement
>      Security Level: public(Regular issues) 
>          Components: Documentation, Website
>            Reporter: Javier Candeira
> It occurs to me that as a new inductee into the project I'm in a privileged position
to update and restructure the documentation as I take the project in, and it would probably
be a better first task than to go after individual bugs.
> This is how I'd go about working on restructuring the documentation:
> - move the old wiki content to confluence and 301 all pages to the new
wiki. No new content added. 
> - track all links and references to old wiki in, and rewrite them to
point at new wiki. Still no new content added.
> - then I would start triaging documentation bugs. There are many tasks that are better
done by a newcomer, since we need to follow the documentation or be confused by it.
> This is what I'd need:
> - To be added to the confluence wiki contributors list (username: candeira)
> - To be added to the old wiki contributors list (username: JavierCandeira)
> - Optionally, to have a test confluence wiki so I can test migrating the old one to the
new one via scripts without making public changes until bugs have been ironed out.

This message was sent by Atlassian JIRA

View raw message