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