ClojureDocs week 1, feedback summary and future plans.

[zkim]

Hi All-

Well it's been a little over a week since ClojureDocs.org launched,
and I wanted to take a moment to summarize the feedback up until this
point, and frame the plan moving forward.


First, what was done well (based on feedback)?
* Centralized searchable documentation
* 'Used-in' and 'Vars-in' sections
* Ability to add and edit per var examples
* Ability to search
* Above features for 3rd party libraries

What needs work (no particular order)?
* Visual layout
* External non-web access (Examples API, REPL integration, etc)
* Versioning
* 3rd Party Lib import
* Monitoring of user generated content
* Administration / development of the site
* Categorization of vars (ex. cheat-sheet functionality)
* Search experience
* Open-sourcing the codebase



Moving forward I'd like to focus on three general areas (in order):

A. The clojuredocs.org experience centered around Clojure core and
contrib, meaning that I as a user would be able to find the
information I'm looking for on var usage quickly and easily (in core
and contrib). Also tooling around monitoring user-generated content.
I'd like to use the completion of this area as the demarcation between
alpha and beta.

B. Finding the right people to administer and monitor the site,
contribute to the source code, and take care of the other people
aspects of the site (and giving those people the tools to do the job
efficiently). I'd like to pull this group from those in the community
that significantly contribute over the course of 'A' (and up until
this point). Open-sourcing of the codebase will happen at this point.

C. Support for third party libraries. This means an automated import
tool, and giving third party libraries the same features that core and
contrib enjoy.



Where the specific 'needs work' feedback points fit into the above
areas:

1. Visual Layout (A)
I think the overall page layout is fine, but I think that readability,
specifically on the var pages could be better. Chris Schreiner has
offered to make an attempt at an improved visual experience (depending
on his schedule), and if anybody else would like to take a whack at it
send me a css file and I'll test it out. I'm going to lump in fixing
the var urls with this one (they really bug me).

2. External non-web access. (B)
This touches on several specific points of feedback, including Stu's
continuity point and REPL access. I'd like to support all the
mechanisms available to users of the site (search, lib to ns, lib to
vars, ns to vars, and example lookup by "ns/var"). Query parameter
input and JSON and / or XML output.

3. Versioning (A)
This would be a mechanism to choose the maximum version number of the
vars displayed on the lib and ns pages, and the ability similarly
restrict search. I'd like to use the 'added' metadata value for this,
that way the onus is on the library maintainer(s) to keep this correct
and up to date, not us. Perhaps down the line we could track this
ourselves based on lib import cycles, which would provide diffs at the
var level.

4. 3rd Party Lib Import (C)
UI / backend for 3rd party lib writers to import their own projects.

5. Monitoring of User Generated Content (A)
This item consists of establishing example formatting guidelines,
providing tooling (to everybody) to monitor new / edited examples and
other user generated content, and refining the user's experience
around adding content. I want to make monitoring as efficient as
possible, which includes making it easy for users to 'do the right
thing'. The goal is to reduce the monitoring process to a quick
double-check (if possible).

6. Administration / Development of the Site (B)
Keeping the servers running, providing direction for the site, adding
features, pushing changes, etc. I'm definitely willing to fill this
role for the long haul, but I'd like to get some others at this level
to increase the bus factor a few points. It's difficult to elucidate
the exact process behind finding the right people for these roles (it
can't hurt to provide well thought out suggestions and feedback about
ClojureDocs).

7. Categorization of Vars (Cheat-Sheet like functionality) (A)
I'm working on this with the help of Johannes Friestad and his
excellent quick-ref (http://faustus.webatu.com/clj-quick-ref.html).
ClojureDocs will support categorization along familiar lines
(Collections, Data Types, Arithmetic, etc) as well as user-editable
single line documentation to improve visual scanning and
differentiation between vars with similar names. It's a mostly manual
process at this point, but it's a great way to figure out the domain
for eventual automation for contrib and 3rd party libs.

8. Search experience (A)
The search capabilities are very simplistic at this point, and good
search is something that I feel is hugely important to a good
documentation site. The good news is that there are only a few
different types of data to search (namespaces, ns docstrings, var
names, var docstrings, and examples). Also, because of Clojure's
relatively simple grammar we could probably provide great code search
as well. As of now ClojureDocs is using Sphinx, so if you've got any
experience tweaking a Sphinx based search engine drop me a line.

9. Open-Sourcing the Codebase (B)
I'm thinking EPL 1.0



So that's the plan for moving ClojureDocs.org forward. I should
mention that unless there's an extremely compelling reason to change
the overarching areas (A, B, C) they will stay as-is. Everything else
is up for discussion, so please let me know if you've got any
questions, comments, or concerns.

Also, if you're looking for a way to help in the short term (other
than feedback / discussion), please add a few examples and share the
pain-points you encounter.

-Zack.

[zkim]

Quick addition (thanks Avram):

5a. Voting Up (and Down) of content (A)
This falls under monitoring (making sure the best examples are at the
top), and would be a way to add a bit of self policing behavior to the
site.