apache / apache/couchdb

DesignDocument section suggestions

Open
#4,224 1 comment 0 reactions 0 assignees View on GitHub
documentation patches-welcome
Dominant language
Erlang
Stars
7k
Forks
1.1k
Avg merge
1d 16h
Merged PRs (30d)
9

Description

I am currently trying to understand design documents and I tried to make some suggestions out of my recent experiences with the documentation.
I still don't fully understand everything, but I hope a few things are a good idea.

1. Most common use-cases first.
For example, "views" with map/reduce should be explained first, because most readers would look for that. Maybe they could even be simply shown in the overview and linked. But also the obsolete functions like `show` should be on a separate page. A new reader shouldn't have to scroll over them, as they are deprecated anyway.
2. Extend the general section with a general overview over the functions. The in-depth details are good to look them up. But first f all you need to know whats possible.
2. Have some examples with full design documents. As a new reader, you may want to try out the examples, but there is no single example on how the actual design documents look like. You find a single reference to the `views` field in the chapter about views, but I had to look somewhere else, that this is an object with subobjects for each view. The same goes for others like `mapfun`.
3. Explain the difference between `mapfun` and `views/map`. Maybe this should be in a general section as well.
4. Rereduce is only explained with `Rereduce is used for additional reduce values list`. A usecase would be nice here as well.

As I said, I didn't understand everything yet, because of that, this is no PR. But if some parts seem like a good idea, I'd be happy to help.

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the CouchDB documentation sections covering design documents, views, map/reduce, show, mapfun, and rereduce. Compare the existing explanations with the suggested use cases, overviews, full examples, and distinctions. Done should mean that any selected improvements are clearly scoped and reflected in the relevant documentation.

Written by the indexing model from the issue text.

Assessment

Domain
databases, documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.