[
https://issues.apache.org/jira/browse/COUCHDB-2350?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14165006#comment-14165006
]
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 couchdb.apache.org
< kandinski> CouchDB Team: this page has no business being a wiki. This is
maintained by the team in couchdb.apache.org
< 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
couchdb.apache.org or docs.couchdb.org
<+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.
<+dch> http://bikeshed.org/
< 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 docs.couchdb.org
> ------------------------------------------------------------------------------
>
> Key: COUCHDB-2350
> URL: https://issues.apache.org/jira/browse/COUCHDB-2350
> 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 wiki.apache.org pages
> to the new wiki. No new content added.
> - track all links and references to old wiki in docs.couchdb.org, 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
(v6.3.4#6332)
