couchdb-dev mailing list archives

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

    [ 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)

Mime
View raw message