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 Fri, 10 Oct 2014 20:45:34 GMT

    [ https://issues.apache.org/jira/browse/COUCHDB-2350?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14167475#comment-14167475
] 

Javier Candeira commented on COUCHDB-2350:
------------------------------------------

Hi, [~andywenk]. Thanks for your kind words. 

The way I see the hierarchy of information published by the CouchDB project is as follows:

* Website: information about *the project*. The most slow-moving, as it doesn't change from
release to release. 

* Docsite: information about *each release of the software*. Some bits are slow-moving because
some bits of CouchDB don't change that often, and some bits are fast-moving because some bits
have to change per-release, but in any case the whole of the site gets re-rendered for each
release. Also, information about technical governance (release management, preparing a ) should
be here.

* Wiki: information about the interaction between *the software and the outside world*: how
to install on ubuntu, which new couchapp helper exists, which new python library is cool,
etc. Can change at any time, is the most fluid.

* Blog: news. This is a chronological record of events, emitted as they happen (a *log).

This is not a fast-and-hard rule of classification, but merely a convenient way to ensure
the goals:
1 - We produce correct information and documentation about the project, the software, and
the way they interact with the world.
2 - Users can find that information and be ensured it's authoritative.
3 - Contributors can help fix information/documentation that's out of whack with the truth

One of my first drives is deduplication, so amendments to outdated or incorrect information
only have to be done once, and people looking for information have only one place to look
at. This involves having rules for where things should go. So to the above time-based classification,
I'd add the following overlay:

* Website - Information about governance (Project affairs, Elections) should go here.

* Docsite - Information that has high technical content would go here, despite being slow-moving
and not changing with each release. Contribution, translation, documentation guide. Yes, some
of this information is a mix of governance and technical, but it's still "howto" information.

* Blog - Information to people who aren't necessarily CouchDB users or contributors. I have
suggested, for instance, that the media pack could be a page in the blog. 

* Wiki - Information that doesn't fit in any of the other categories.

>  because they shouldn't be editable by users. I don't think that way. As this is an Open
Source project, every contributor is allowed to edit these contents

Perhaps "no business being user-editable" is not a good way to phrase it, and I need to express
myself better. I'll leave it in the spreadsheet for now (for honesty if someone else wants
to take a look at it), but I'll eventually change it. After all, a week ago I was a user,
and you knew nothing about me, and now I'm rearranging documentation like a boss.

But there are some contributions that can be made "drive-by", without knowing almost anything
about CouchDB and the project (fixing Ubuntu installation instructions, based on having followed
the instructions until they broke and substituted one step) and others that require better
knowledge of the project (Contribution Guide, Code of Conduct, etc).

And there are two ways of reading "no business being user-editable". One is that users shouldn't
be allowed. But the other is that some information should never be left to be edited by users
if they decide to, and to rot if they don't. My example for that is "Current Releases". This
should be in the documentation, changed with every release, and checklisted to make sure it
is. It simply shouldn't be a wiki item.

> So for me, these pages should be moved away if the context is wrong, but not because
they shouldn't be editable by any user.

Right. Let me give you one big example of something that bugs me so much that it was what
decided me to turn up my sleeves and start shoveling documentation around: the "other *ouchDB
and Couch* databases". 

A year ago, as a new user, I was really frustrated jumping around the web reading on the many
options. First, because I had been tasked for my job with selecting something to use, and
I had not only to compare Couch to Mongo etc., but Couchbase toCouchDB to BigCouch to rcouch
to everything else. Then, I needed some mobile software, and again I was jumping around the
web looking at touchbase, pouchbase, couchbase lite, without one central place. The current
wiki had not one, but two empty pages suggesting they should go there. 

I think this is important enough that it should be in the documentation, and updated with
every release (I have volunteered to write a first draft). This is not some sensitive information
that needs to be protected from editing by grubby fingers. Indeed, it could be written by
keen outsiders almost as well by CouchDB insiders. But leaving it on the wiki makes it an
"out of sight, out of mind" problem for project contributors, and doesn't signal to newcomers
that yes, this information is considered by the project as central enough that it's not relegated
to the "someone else can write it" bit of our documentation.

So please consider every one of my suggestions as informed by two recent experiences...

- trying to learn CouchDB from zero, 
- trying to start contributing to documentation,

... and trying to fix those experiences for the next person to arrive.

> 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
>            Assignee: 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