couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jan Lehnardt <...@apache.org>
Subject Re: Getting rid of file lists in documentation Makefiles
Date Tue, 21 May 2013 17:07:14 GMT

On May 21, 2013, at 18:55 , Noah Slater <nslater@apache.org> wrote:

> Another way of looking at this is that by moving things to the docs, you're
> putting it behind a "commit bit" wall. That's appropriate in a some
> instances, but not in others.

> 
> The wiki is open to developers, and good for collaboration, coordination,
> sharing resources, drafting things, etc. It's also used as a "noticeboard"
> in a few instances. This is why I think the wiki is better for project /
> community level stuff.


Another another way of looking at this is that we make it accessible to the
GitHub-on-website-fork-and-edit-and-pullrequest instead of the shoddy wiki
that everybody hates and nobody works on because the experience is so abysmal.

Jan
--


> 
> It's not just Release_Procedure I'm concerned about. I did a quick survey
> of some of the top pages...
> 
> ... But before I do the rundown, TL;DR: This seems complex. We might want
> to consider each wiki page separately.
> 
> Quick rundown:
> 
> http://wiki.apache.org/couchdb/Weekly_News
> 
> - This is a WIP. I actually want to move to having an index here too, where
> each week's weekly news is drafted on the wiki. This would be a
> collaborative effort between developers and committers.
> 
> http://wiki.apache.org/couchdb/SourceCode
> 
> - This is in the "would be on the website if we had one" category.
> 
> http://wiki.apache.org/couchdb/Release_Procedure
> http://wiki.apache.org/couchdb/Test_procedure
> 
> - Both of these change quite frequently
> 
> http://wiki.apache.org/couchdb/Release_Calendar
> 
> - This makes no sense in the docs, because it's time-based statuses. It's
> more like a notice board.
> 
> http://wiki.apache.org/couchdb/Committer_Election_Process
> http://wiki.apache.org/couchdb/PMC_Election_Process
> http://wiki.apache.org/couchdb/Community_Guide
> 
> - Both WIPs. Will flesh these out over time. More of the "how we work" /
> process stuff. Expect there to be more of this over time. Having it on the
> wiki lets me do this WIP stuff without worrying about lots of messy stuff
> ending up in our manual.
> 
> http://wiki.apache.org/couchdb/Roadmap_Process
> http://wiki.apache.org/couchdb/Merge_Procedure
> 
> - More examples of docs that are not official, but are being *drafted* on
> the wiki. These would not be appropriate to include in the docs at this
> stage.
> 
> http://wiki.apache.org/couchdb/CouchDB_in_the_wild
> http://wiki.apache.org/couchdb/People_on_the_Couch
> http://wiki.apache.org/couchdb/CouchDB_tools
> 
> - This is more of the "noticeboard" type page. I see this as a way for the
> community to collaborate, communicate, etc. It wouldn't be appropriate to
> move this information to the manual or the developer handbook.
> 
> http://wiki.apache.org/couchdb/CouchDB_meetups
> 
> - Another one of the noticeboard type pages. This is time-based
> information, and is good on the wiki for collaboration. Would not be
> appropriate in the docs.
> 
> http://wiki.apache.org/couchdb/Getting%20Help
> 
> - Not sure about this. This is of the "would be on the website if we had
> one" category. If we put this in the docs, would it be obvious for people?
> How would you find it? Seems like a good case for being on the wiki?
> 
> http://wiki.apache.org/couchdb/Frequently_asked_questions
> http://wiki.apache.org/couchdb/Breaking_changes
> http://wiki.apache.org/couchdb/Error_messages
> http://wiki.apache.org/couchdb/Troubleshooting
> http://wiki.apache.org/couchdb/Known_Problems
> 
> - Good candidates for the docs.
> 
> http://wiki.apache.org/couchdb/Development
> 
> - Some good candidates here for the developer manual.
> 
> http://wiki.apache.org/couchdb/Build_Process
> 
> - This seems like a collaborative page. By which I mean, seems like the
> sort of thing to keep out of the docs. The wiki is sometimes used as just a
> scratch pad for people to share ideas in an informal way.
> 
> http://wiki.apache.org/couchdb/Documentation
> 
> - Another one that looks like a temporary collaboration page. Could
> probably do with an overhaul. After the update, this would probably be in
> the "would be on the website if we had one" category.
> 
> http://wiki.apache.org/couchdb/ContributorWorkflow
> 
> - Good candidate for the developer manual?
> 
> http://wiki.apache.org/couchdb/Related_Projects
> 
> - More of a noticeboard type page. Should be on the wiki for collaborative
> purposes.
> 
> 
> 
> 
> On 21 May 2013 17:23, Jan Lehnardt <jan@apache.org> wrote:
> 
>> 
>> On May 21, 2013, at 17:25 , Noah Slater <nslater@apache.org> wrote:
>> 
>>> I think the idea of a "Developer Handbook" is a good one.
>>> That's separate from a "CouchDB Manual" though.
>> 
>> I’m roughly modelling this after the FreeBSD project which has
>> 
>> http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/
>> (this corresponds to our “docs/”)
>> 
>> and
>> 
>> http://www.freebsd.org/doc/en_US.ISO8859-1/books/developers-handbook/
>> 
>> (and a few more).
>> 
>> So they have separate handbooks for this, and I think eventually that
>> makes sense for us as well, but I thought it was easiest to get started
>> with the developer handbook as a chapter/section in our docs/ until it
>> is substantial enough to make into its own.
>> 
>>> For now, let's focus on getting the manual up to scratch, and let's keep
>>> the handbook stuff on the wiki.
>>> 
>>> We can re-evaluate the situation later. I'm not married to it. :)
>> 
>> I want to start this asap because we have some thing flying around
>> elsewhere that would benefit from getting into a definite location.
>> 
>> Note though that Release_Procedure, while totally applicable to a
>> developer handbook, doesn’t have to migrate today if you prefer that.
>> If so, I’d suggest we just put a link into the developer handbook that
>> points to the wiki.
>> 
>> Does that make sense?
>> 
>> Jan
>> --
>> 
>> 
>>> 
>>> 
>>> 
>>> On 21 May 2013 16:00, Jan Lehnardt <jan@apache.org> wrote:
>>> 
>>>> 
>>>> On May 21, 2013, at 15:27 , Noah Slater <nslater@apache.org> wrote:
>>>> 
>>>>> Actually, I prefer that project documentation be kept on the wiki.
>>>>> 
>>>>> The docs that we have in the source are the "CouchDB Manual" (as I
>>>>> have titled it), and I see them as a reference work for CouchDB itself.
>>>>> Setting it up, configuring it, using it, etc.
>>>>> 
>>>>> I see the wiki as more a place for the project / community to document
>>>> and
>>>>> organise itself. Consider that our homepage is a single HTML page. Most
>>>> of
>>>>> what we'd usually have on a website was moved to the wiki. So, I'm
>>>> talking
>>>>> release process, release calendar, source locations, active releases,
>>>>> committer election process, PMC election process, and soon, by-laws,
>>>>> community guides, etc.
>>>>> 
>>>>> I'd like to keep this stuff on the wiki for now.
>>>> 
>>>> I want to start a section in there that is called “The Developer
>> Handbook”.
>>>> The release docs would fit right in there, but this is your call
>>>> ultimately,
>>>> maybe we can have a pointer to the wiki from the docs/ then?
>>>> 
>>>> Jan
>>>> --
>>>> 
>>>> 
>>>> 
>>>> 
>>>>> 
>>>>> 
>>>>> On 21 May 2013 13:20, Jan Lehnardt <jan@apache.org> wrote:
>>>>> 
>>>>>> On 21.05.2013, at 11:37, Dirkjan Ochtman <dirkjan@ochtman.nl>
wrote:
>>>>>> 
>>>>>>> On Tue, May 21, 2013 at 11:33 AM, Jan Lehnardt <jan@apache.org>
>> wrote:
>>>>>>>> It is all documented here:
>>>>>> http://wiki.apache.org/couchdb/Release_Procedure
>>>>>>> 
>>>>>>> Oh, good. We should definitely pull stuff like that into a developer
>>>>>>> chapter of the docs, IMO.
>>>>>> 
>>>>>> Go for it :)
>>>>>> 
>>>>>> I think we have a rough consensus on moving most of the wiki into
the
>>>>>> docs. Anyone, feel free to act on this!
>>>>>> 
>>>>>> Jan
>>>>>> --
>>>>>> 
>>>>>> 
>>>>> 
>>>>> 
>>>>> --
>>>>> NS
>>>> 
>>>> 
>>> 
>>> 
>>> --
>>> NS
>> 
>> 
> 
> 
> -- 
> NS


Mime
View raw message