Organizing the wiki

[fu]

We've been gradually building up articles on the wiki, which is good because wiki == good, but it can be a bit overwhelming for someone new because they won't know where to start.

I propose reorganizing the articles under the Development section: I don't want to constrain things too much, but I think slotting things in more clearly will be helpful for both new and old alike.

We're partway there because of the fine work people have put into Dev Getting Started, but I want to sit down and rethink the split a bit.

What I have in mind is to split up the pages into one-time steps and steps that have to be repeated over and over again, and revise how things are arranged and highlighted in Dev Getting Started. So instead of having a Bugzilla page and a Github page and etc, we have something like the following:

• front page

  1. Dev Getting Started

     • one-time setup
       • dev environment (scratch installation / getting a hack)
       • bugzilla (registering, username conventions)
       • github (forking etc)
       • CLA
     • working on stuff (the basics)
       • programming guidelines
       • finding things
       • claiming a bug -> submitting a pull request, including conventions etc
       • editing in case of a review
       • updating code (dev maintenance)

  2. Development

     This is more specific resources. Everything under here to be a subpage of /Development?

     • everything in the getting started section
     • submitting hotfixes on a release branch /Development/Release
     • setting up various modules /Development/Setup? Tools? Server?
       • schwartz /Development/Setup/Schwartz
       • gearman
       • search / sphinx
       • memcache
     • howto /Development/Howto
       • new userprop
       • database table (create, edit)
       • edit a database table
       • memcache
       • beta feature
       • enable shop items
       • enable paid time
     • stuff under /admin (/admin/pay, etc)
     • explain stuff under /dev (/dev/classes, /dev/eventoutput, etc)

The examples provided aren't definitive, just examples of what we have and need off the top of my head. There are plenty of articles on the wiki that aren't yet in this list but could fit (most probably under /Development).

Would this structure be helpful for you? What would be most useful to highlight in Dev Getting Started? I'd like to request that we focus on overall structure before specific page suggestions as much as we can, so that it's easier for people to find what they need in the pages we already have.

Comments

[ninetydegrees]

Would this structure be helpful for you?

Yes and yes and a hundred times yes. What would be even more useful is exactly what you've done here that is to say a page linking to all the different articles and showing how everything is connected so that, depending on what you need, it's easy to see how you can get started *and* it's easy to find the precise little bit of info you were looking for. What I found hard about the current wiki is that I couldn't find what I needed because a) I didn't know I needed it (it was unlinked from other articles, it was in a different cat or it wasn't mentioned as a necessary step of the workflow) or b) I didn't know what it was called and search didn't help (e.g. 'version control' makes sense to someone who knows what 'version control' means). See what I mean?

[yvi]

Yes, that would be very helpful.

[codeswitcher]

I really like the one-time-setup-howtos/regularly-occurring-howtos dichotomy.

That said, your list looks very how-to centric. How-tos are awesome, but the very first thing I want to know when I start working on something is an orientation to how its organized and why, and a glossary of in-house jargon (e.g. "in dw/lj-ese a 'post' is called an 'entry'"). I love things like ER diagrams, layer schematics, and class inheritance illustrations, for quickly getting oriented to how things are organized. I want references and explanations, not processes to follow. Right now pretty much all of Dev Getting Started is "Do this, then this other thing", which I find not very helpful.

I find documentation organized in parallel with the structure of the actual code (e.g. "here's a list of directories and what they all hold") to be marvelously useful when I'm staring at the code puzzling, "What does this do?". But they're much less useful if I'm trying to figure out where in the code to find something I already know about from the user interface, and don't know where to start looking, which is a more common case for me.

A thingy which if you don't have it might be a powerful addition is a discussion of/reference to what I'll call the Core User Inspectable Assets, which for dw would be things like "Journals" and "Users" and "Posts/Entries" and "Communities" -- the kind of entities which end users experience of the application. The discussion of "Journals" would explain how journals are represented in the db, how they relate to other CUIAs such as Users (which is interestingly close to identity in dw, but not quite -- and useful to disambiguate for developers coming in from some other world like WP where there is a strict division of Blog from User), what resources do what as part of instantiating the "Journal" asset to users. Yes, this would be a pretty big document, and massively crosslinked to other stuff. And it would be seriously redundant to parts of "Users" and "Entries" and "Communities" -- and that's okay. The point is to present an asset-centered view of the project so someone coming in saying, "I want to do something to 'journals'," can get a journals-centered view of the code for rapid orientation. It's a way of meeting the developer where they are.

Another way of putting it is that documenting the Core User Inspectable Assets is documenting a slightly higher abstraction layer, the systems the code and db objects are organized into. This middle abstraction layer is actually how we mostly think about code, both what is most useful to learn and what is least often documented.