Updating Documentation
Drew Haven
- A wiki-like website where any yesod hacker can contribute. Right now it sounds like the documentation has to go through Michael, and that puts a barrier up to helping out and just fixing it whenever an error is seen.
- There are plenty of good wiki frameworks out there, probably even some hosted ones. Anyone have any good recommendations?
- The book is very linear, which makes it hard to flow naturally from topic to topic. I think something more like a web of documentation, where each topic links to some related topics at end would be nice, with tags, index, and search as well. I think tags are preferable to sections or chapters.
- Shorter articles, so you don't have to read a long chapter to get to the part you want.
- Clearly different articles for guides vs. theory. When I'm learning sometimes I just want a quick article for "How to add a new route" or "Setting up basic CRUD" without having to read through an aside about the type signatures or specifics of the routes quasi-quoter. These would be better handled as links. I really like the idea of a choose-your-own-adventure walkthrough for setting up your first app. It's how I learn best. Others may have other ideas though.
Drew Haven
drew....@gmail.com
Michael Snoyman
As someone else has pointed out, we *do* have the wiki. The fact that
people aren't aware of it is clearly a problem, and the problem almost
certainly lies in the site. Let me explain quickly how the site came
to be in its current (bad) state.
The company I work for (Suite Solutions) works on XML-based
documentation services. One of the products we're pushing now is
called Suite Share, which actually shares a number of features of the
Yesod site. But it obviously doesn't support all of them (e.g.,
Haskell syntax highlighting). To try to lessen the burden of
development, I based the current site on an older version of the Suite
Share codebase[1]. This has had a very bad effect: it makes it
impossible for others to contribute to the site, and since Suite Share
itself is moving in a direction that doesn't help yesodweb.com at all.
So let's start over with what we want, and figure out the best
community approach to things. What do we need out of a site and
documentation?
* Homepage and other "marketing" material
* The book content. I currently store this in an over-engineered XML
format (also to do with my work life), but instead of putting that
complexity into the site, I can preprocess the content to HTML.
* The blog. Currently only Greg and I can make blog posts, but I'd be
happy to add others to that list if they are interested.
* Wiki/user submitted docs
* Developer docs.
We don't *have* to use Yesod for everything here. For example, we
could decide to put the Wiki content on Github instead, or use Gitit
(we did so in the past). But I think we're going to want to just go
for the gold and write the whole thing as a Yesod site. So let's draw
up a theoretical set of requirements for how this site would work:
* Let's store all the content in a Git repo. We'll make this repo part
of the yesodweb organization, and give just about anyone who wants it
commit access.
* The site will recognize both HTML and Markdown content.
* The Wiki will be world-writable (probably logged-in users only) and
only allow Markdown content. This might be a good time to mention that
I've been working on a replacement Markdown package, but haven't had a
chance to finish it yet.[2]
* We'll have a separate section in the Git repo for non-Wiki pages.
This is where things like the homepage content, contributor page, etc
would go. In other words, stuff we don't want everyone to see.
* We'll run a cron job to automatically sync the live site content
with the Github repo, with some simple merge algorithm (likely
whatever's on Github trumps). This way, people can edit content
locally instead of needing to go through the web interface for
everything.
* Like now, any page can be posted as a blog post. This helps with
something called single-sourcing, another way of saying DRY in the
documentation world.
I'm happy to discuss all of this. If it's not clear, my goal is to get
the rest of the community to participate more in the documentation
side. I think there was a huge communication gap simply because I
created a crappy Wiki and no one understood that that's where
documentation could go. So let's solve the problem by creating a
better one now.
As far as who's going to write this thing: I wouldn't mind if someone
wants to step up to the plate on this, though I'm guessing the more
likely scenario is I'll write a first version and people start sending
pull requests. If anyone's interested in spearheading this instead,
let me know.
I think having a more community-based site should be a prereq for the
0.10 release, so that from 0.10 to 1.0 we can have a strong docs
focus.
Michael
[1] Historically, it really went the other way around, but that's a side point.
[2] https://github.com/snoyberg/markdown
Drew Haven
Drew Haven
drew....@gmail.com
Michael Snoyman
of unified data access/storage, with the downside that we can get
merge conflicts (editing on the Wiki or editing on Git). I don't
actually have a strong opinion which way to go.
A Git backend for Persistent might be interesting, but I don't think
it would be very practical. I was thinking of just doing normal file
access from the site, and having a cron job run every so often and
commit/pull. Not a perfect solution (we could lose some history if two
edits happen in the same windows), but simple enough. I also don't
mind taking a different approach on this one.
Felipe Almeida Lessa
> * Developer docs.
IMHO, this is what I miss the most, good API documentation. Some
functions are well documented, some aren't documented at all.
Regarding this, I'd like to see two things:
- First of all, let's start rejecting commits/pull requests that do
not have Haddock docs. So if you want to add something, at least its
API must be documented.
- We need to document what's already done. I don't have any magical
ideas here, but I'm playing with the idea of (myself) taking some time
every so often to document some functions. I'm usually comfortable in
reading Yesod's source code, so figuring out what something does is
not a problem. I just need to bite the bullet and do it.
While API docs are not a replacement for other kinds of documentation,
IMO the book is already a very good kickstart and having nice API docs
would finish it. For example, suppose you want to see the details of
how the Julius syntax works. If you read the book about Shakespearean
templates, you know *where* the API docs are. If we had a nice
description of how Julius works on its module, we would be done.
Cheers,
--
Felipe.
Michael Snoyman
Let's take it a step further: if everyone who's been participating in
these discussions picked two to four modules to "adopt" and fill out
missing API docs, this whole process would go by very quickly. This is
actually something we should do *before* the 0.10 release, because
having someone actively looking at every module is a good way to
determine where the API sucks.
If people are willing to do this, please speak up now. I think the
best way to keep this organized would be to put up a spreadsheet on
Google Docs with a list of every module we want to address. Then
people can sign up for which ones they want to take care of, or where
appropriate, mark some modules as already "good enough."
Michael
Felipe Almeida Lessa
> Let's take it a step further: if everyone who's been participating in
> these discussions picked two to four modules to "adopt" and fill out
> missing API docs, this whole process would go by very quickly. This is
> actually something we should do *before* the 0.10 release, because
> having someone actively looking at every module is a good way to
> determine where the API sucks.
>
> If people are willing to do this, please speak up now. I think the
> best way to keep this organized would be to put up a spreadsheet on
> Google Docs with a list of every module we want to address. Then
> people can sign up for which ones they want to take care of, or where
> appropriate, mark some modules as already "good enough."
I'm in for the API documentation efforts! =)
Cheers,
--
Felipe.
Michael Snoyman
Alright, I put together a little script[1] to grab the modules and put
them in a Google Doc[2]. It's world-writable, so anyone should be able
to add their name. To sign up, put your name in the "Status" column,
and when you finish, just put a "Done" after it.
One last note: please be sure to do this work on the *most recent
code*. I just merged the beta branches to master for the persistent
and yesod repos, so as of now, master is the most current code on all
four repos. There are still a few things that aren't building
properly, most notably mongoDB due to its restrictive upper bound on
monad-control. Hopefully we can get that fixed upstream soon. I'll go
ahead and release a few dependencies right now, let me know if you
notice any packages that aren't on Hackage.
[1] https://gist.github.com/1533274
[2] https://docs.google.com/spreadsheet/ccc?key=0AsM1GETpq89EdHhLUUwwak0yQ3NpVWp0d25qbm5FRXc
Drew Haven
Drew Haven
drew....@gmail.com
Michael Snoyman
site, so hopefully he'll be able to help on the new site too. I think
I'll try to get a base site started at the beginning of next week so
that we can get the ball rolling, and then I'd love to get pull
requests. (Again, if someone wants to take the lead on this instead,
feel free.)
ζεβαστοσ
end best practices.
Some things we need:
- Flatter DOM
- Less HTTP requests
- More attractive front-page
- Correct HTML (structure)/CSS
And just generally a more attractive/useable website. I'm willing to
put in a lot of hours to get Yesod the website it deserves. Just need
something to fork \o/
On Dec 29, 11:21 pm, Michael Snoyman <mich...@snoyman.com> wrote:
> Bas Dirks has been in contact with me about fixing up the CSS on the
> site, so hopefully he'll be able to help on the new site too. I think
> I'll try to get a base site started at the beginning of next week so
> that we can get the ball rolling, and then I'd love to get pull
> requests. (Again, if someone wants to take the lead on this instead,
> feel free.)
>
>
>
>
>
>
>
> On Thu, Dec 29, 2011 at 7:37 PM, Drew Haven <drew.ha...@gmail.com> wrote:
> > The API is definitely something we should have, definitely before the 1.0
> > release and I like the idea of pushing documentation for 0.10.
>
> > We will still need to expand the book though. When starting a new project,
> > there are a lot of functions out there, and API docs tell you what the
> > functions do, but they don't really tell you how to do something if you're
> > new, and don't tell you the best way to do something if you found a way that
> > works but isn't very elegant. This is definitely a good start though, and
> > we can continue to think about expanding the wiki/book as we move to 1.0.
>
> > We should still figure out what we want to do for the wiki. I'll say that
> > if no one else wants to work on it, I'll take a stab at it in January.
>
> > Drew Haven
>
> > On Thu, Dec 29, 2011 at 2:04 AM, Michael Snoyman <mich...@snoyman.com>
>
> >> On Thu, Dec 29, 2011 at 11:28 AM, Felipe Almeida Lessa
> >> > On Thu, Dec 29, 2011 at 7:21 AM, Michael Snoyman <mich...@snoyman.com>
Michael Snoyman
the dynamic content, and apply no styling. Then it's all yours for
styling. Sound good? I think I'll have it ready by Tuesday of next
week. Also, it's going to be using the Yesod 0.10 beta (which is why
it's taking me a bit longer to get ready, I'm cleaning up a few things
in the scaffolding first).
2011/12/30 ζεβαστοσ <i...@basdirks.eu>:
Bas Dirks
On Friday, December 30, 2011 at 12:15 PM, Michael Snoyman wrote:
My plan is to put together a skeleton site that can properly pull inthe dynamic content, and apply no styling. Then it's all yours forstyling. Sound good? I think I'll have it ready by Tuesday of nextweek. Also, it's going to be using the Yesod 0.10 beta (which is whyit's taking me a bit longer to get ready, I'm cleaning up a few thingsin the scaffolding first).
2011/12/30 æåâáóôïó <i...@basdirks.eu>: