Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Lithium Documentation Hack Day! #901

Closed
blainesch opened this Issue · 35 comments
@blainesch
Collaborator

The biggest suggestion, from our users, is for better documentation so on Saturday, May 18th 2013 starting at 9am CST (-6) to 5pm CST we are having our very first documentation hack day!

This is when we all get together and add as much documentation do the code comments or the li3 manual.

Right now, list below things you wish were more documented such as classes, methods, procedures, or anything you just don't understand after reading the current documentation!

Later, on May 18th head into #li3 on irc.freenode.net and we'll get to work! We can give you something to document, or feel free to work on one you know a little about or want to learn about by documenting it. We'll keep the discussion going to prevent overlapping.

Anybody can contribute, so I'll see you then!

Add to Google Calendar

@fduarte

Great idea! I would just like to add that it's not only plain documentation that we need, we need EXAMPLES. Thanks!

@rapzo

Count me in mates!
I'd like to suggest, to make it even more interesting, to wrap up something like docco for quick api access. I know it used for small stuff such as backbone and underscore but long is the waiting for a full page load on each package browsing the docs.
I'm terribly flooded with work until that date but i'll try to plug docco or a hack of it with the doc parser, and if i manage not to, if others like the idea, grab it :-)
But for now, what ya guys think about a gigantic page with all the api and its stuff?

@tmaiaroto
Owner

I'm down. Happy to provide some examples too.

@jails
Collaborator

@marcghorayeb on which planet are you living guy ? ;-)

@marcghorayeb

@jails oops, read that a little too quick haha

@gianbasagre

More documentation on testing please. Probably a guide on using other testing framework like PHPUnit.

@Ciaro

I feel like people could benefit a lot from a good example application. @see http://www.lithium-framework.com/viewtopic.php?f=20&t=45 for further argumentation (+ context).

@marcghorayeb

@Ciaro Yes, a sample application that exposes most of lithium design philosophy could definitely be helpful !

@tmaiaroto
Owner

Sorry, this is a little lengthy...But to quickly sum it up. I think Lithium documentation is completely separate from examples...Here's my thinking (and proposal, I'll do all the leg work).

Once upon a time I was thinking about building a tutorial app. That would live in its own repo and each branch would be a different example. Each branch would have a matching video tutorial/screencast.

So I actually did that, but wasn't happy with it. I since created https://github.com/tmaiaroto/li3_bootstrap which looks a lot better and uses Lithium Bootstrap instead of some basic flat looking 960gs based thing. I use Lithium Bootstrap for all of my projects since it speeds my development along in a very fast way. However, I focus on MongoDB and as such most of the libraries for it don't really consider MySQL.

I'm thinking about building a tutorial/example app again, but instead of a standalone app, doing it library based instead. li3_examples or li3_tutorial or something.

This would allow you to bring in the examples library to any application you're building.

However. I still want things to more or less look the same, draw from base classes, follow some conventions, etc.

So I'm thinking two libraries (and then optionally more).
One for a "dashboard" and base classes, etc. and then one for the actual examples. Having the main driving dashboard library automatically show a listing AND clone/checkout the example libraries would be ideal so you don't need to manually do it...But I suppose that's not a big deal. Now. Everyone else who would like to create a tutorial could do so by having their own tutorial repo...What I mean by that is their own library that sits in a Git repo and has branches for all the different tutorials they are creating. This would ideally hook back into the main "dashboard" library so that they got exposure (would likely be a manual change to that library - automatically including/approving/blessing things might be dangerous). Of course I would also grant several people access to my tutorial library so they could make branches under "li3_examples" or whatever it may be. More or less the "official" one (if I can be so bold).

This can act as a standalone site that's hosted on the web too...While you can't interact with it (though I had some ideas for that too - won't get into it now) you can see the videos and read about how to set up exactly what you're looking at locally so you could play around with the tutorials. Sandbox. Whatever.

I can whip this up fairly quick since I can yank out what I'm doing (there's a command class to keep Twitter Bootstrap and Font Awesome compiled and up to date, etc.) with Twitter Bootstrap in the li3_bootstrap project and apply the same kind of filter technique to look for templates in certain areas, etc. This provides a very consistent base for anyone looking to then create a tutorial. More than just a consistent UI and base classes and utilities to draw from, it provides a guide for creating tutorials so that we're all consistent in how we build our tutorials. Of course many examples would be more standalone to not be confusing (we don't want to tell people use the example/dashboard library for all your apps - thought perhaps why not draw from it?) but I think each example could leverage the example dashboard app so that each example could have that consistency and a nice UI with documentation etc (perhaps leveraging something like this: http://jquery-jkit.com/sourcemakeup - which @rapzo led me to from docco).

Thoughts?

@rapzo

Damn man, there's a php implementation of docco!! Why didn't i even think of it? Nice one!!
I did some playing with your li3_bootstrap repo some months ago and it sure is solid so, :thumbsup: for using it. I personally don't use bootstrap (started to use foundation on its first releases so, i kinda stuck with it) but i recon its power and use. If it sticks we could propose a challenge: tweaking a theme that fits with lithium, votes during the hack day and the winner puts its work to somewhere (a tutorial, maybe a lithium bootstrap watch or something).
But for a tutorial, i'd think something like a todo app could do the trick, since blogging is dead. But instead of showing dom bindings (like in the client-side framework boom) we could cover the whole 9 yards such as with html templates, json response, command line interface, multiple dbs and plugin goodness (for, say, sending emails, for example). I know it's not as easy as it sounds, even being a simple to-do, but it could provide a great example on where and how to start and also how simple it is to do all that with lithium.
This to-do thingy is easily merged with @tmaiaroto idea. Although i totally agree with the proposal, standalone examples are super useful but i think i looked more to anologue in the starting days and sphere later on, oh! and Minerva too, of course, than i did in the manual.. But that's my opinion. Both are useful. Best scenario was having both. Who knows :-)

@tmaiaroto
Owner

Oh Minerva was a bit sloppy =) Ha, but hopefully it helped you. We can certainly build a todo app for example and Nate has an image gallery with geolocation in there that's also great. We can pull both into the overall tutorial library/app. That main "dashboard" app (for lack of better label) is just a container and link to the examples, screencasts, etc. Think of it as your home base for learning Lithium. It'd link to documentation as well, other sites, etc.

Also, I'm not opposed to using Foundation if everyone would prefer that to Bootstrap =)
One reason I would really consider it is if it's better for responsive layouts...Reading tutorials from iPads is good.
(though I'm a big fan of Font Awesome and would like to keep that integrated still if it works with Foundation)

@marcghorayeb

Having repo that centralises all example libraries/applications is a good idea but a manual that goes step by step (like the blog tutorial but more in-depth) is a must have. Most people are lazy and don't like going through code to understand what it does.
I think the tutorials should be as framework independent as possible. Relying on Twitter Bootstrap or Foundation for admin interfaces is a boon but public websites are all so different and expect different things :)

@tmaiaroto
Owner

@marcghorayeb Good points, but what about the tutorial/example site doubling as a "manual" ? Combine them. Leave the API documentation as is (and we'll jam on it of course). But if the manual bits (all the step by step and more in depth stuff you're talking about) was in a standalone repo that multiple people had access to, then I think it may facilitate adding new examples. Remember, this repo/app will be hosted. Downloading/cloning it is only for your benefit as a developer to A. read it offline and B. work with the code.

"Student" user experience.
You load up this web site and see the "manual" beautifully formatted with code snippets, etc. You can read through that. Then, you notice a blog example that's pretty in depth and has comments all up and down next to code (see: http://jquery-jkit.com/sourcemakeup/ - scroll down a little). Want to actually work with and edit the example? Clone the repo. Don't have Lithium? Never touched it? You are now. You just dove into Lithium in a matter of seconds with a fully functional app/blog/whatever.

"Teacher" user experience.
You clone and/or fork the repo and you make an example...Following the guidelines and using the tools we setup, you can do this quickly. Things like sourceMakeup make it a breeze and you barely need to do anything to your existing code/project to transform it into an example for the public. When you're all done, you make a pull request (this may be in a separate branch or not). It gets merged in and now that manual site gets updated and the world can see the example along with the blog tutorial, etc.

I've written a few tutorials, step by step...It's hard because...
1. Blogs aren't a good platform for complex tutorials (part of why we jumped to screencasts - still not perfect).
2. We're all swamped and/or lazy. It's not quick to write a tutorial in a blog.
3. All of our blogs are scattered and there is no centralized place for people to find these tutorials (Lithium101 did a good job trying).
4. Every tutorial is going to look different and not follow a familiar looking convention. Gets in the way of learning.

A consolidated "manual" app with detailed examples that allows all of us to contribute back to it, levering the power of GitHub in clever ways along with custom built tools that make tutorial writing fast and easy for us, solves all of these problems. Of course there's a lot of details along the way about how to go about such an awesome app. Which I'd love to keep brainstorming.

@nateabele
Owner

At the outset of the project, I saw documentation as being divided into 3 parts (API, Guides, and Tutorials), which are described here: https://github.com/UnionOfRAD/lithium/wiki/Spec%3A-Documentation

Right now, the manual kind of serves as something in between tutorials and guides. It would be better if there were more explicit separation between the two, with more links connecting them. The other issue which I'd very much like to avoid is what happened with Cake, where the manual ended up duplicating a lot of what was in the API docs.

Just like code, the more documentation we have, the more documentation we have to maintain. Let's try to keep it separated into clear, purpose-specific groups and keep the overlap to a minimum.

@jails
Collaborator

:+1:, moreover it may be better to keep this event centered on the manual because I'm pretty sure you all guys know li3 enough to complete & update the manual.

@tmaiaroto, what do you think about starting another issue with your proposals about tutorials ?

@tmaiaroto
Owner

Yup.

@notomato

I'd be keen to help with this as well - particularly the guide.

I think it might be a good idea to sketch out what a guide and tutorials section might actually contain. So guides might be more about explaining concepts and overall patterns, and tutorials will be more explicit how do I do X, Y or Z as well as longer tutorials.

I agree about keeping the docs minimal as well - though I think it could be easier to navigate the existing manual, and it could do with a bit of a restructure.

If we were going to talk about the structure what would be the process?

Btw - lithium101.com is still going - I'm not sure about what to do with it though, it seems like all the info on there might be best in an official site? At least the plugins/snippets sections. @nateabele if you have thoughts give me a shout. Happy to open it up to others for development too - @Ciaro @d1rk have both got in touch previously.

@nervetattoo

Regarding lithium101 @notomato, I'd personally like to see that as the basis for lithify.me, as an open reference implementation using lithium itself. Make the site part of the documentation by deriving most examples from its code.

@gwoo
Owner

@notomato Putting the lithium101 code up would be fantastic. As far as structure, go ahead an submit tickets, pull requests, etc to the UnionOfRAD/manual repo. There is a restructure branch being worked on, but perhaps there can even be some changes to that.

@notomato

@gwoo @nervetattoo Cool - I think I will make it a public repo then. I've just gone through and cleaned it up a little bit and set up a vagrant box so if anyone is interested they can contribute.

As far as the manual goes - I really like the new structure https://github.com/UnionOfRAD/manual/blob/restructure/config/docs/index.json it seems a bit more logical and easy to follow - is there any reason it hasn't changed over to that yet?

The only other thing I think the docs need is some kind of feedback mechanism - I'm all for adding new docs, but I have no idea what other people find lacking or useful.

@davidgolding

From a pedagogical perspective, we could ask where the absolute starting point is and then build outward. So often in our instructional materials we start with tedious stuff like installation, configuration, etc. Maybe a better starting point could be the minimalist approach, like http://github.com/jamalsa/minium where the architecture is as basic as possible. Then we push installation guides to the appendix (making reference to them very early on, of course, but not dominating precious tutorial space with them). I think sinking the readers' teeth into the code with the first tutorial helps to showcase the versatility that comes out of the box with Li3 and has the added bonus of attracting developers working under different paradigms. Screencasts can be effective as well, provided they cut to the chase and have good instructional sequence.

@blainesch
Collaborator

Almost a week ago, I hope you guys are planning for it!

Add to Google Calendar

@mikegreiling

I won't be able to make it that Saturday, but I'll try to do some documentation hacking of my own during the week prior while I'm attending php[tek] in Chicago.

@nateabele
Owner

Derick and Sara and Liz Smith have a few good talks there. Everything else looks skippable.

@mikegreiling

I go for the networking and the "uncon" sessions more than for the talks themselves... and it's a good excuse to visit some friends in Chicago while I'm in town.

@rapzo

Damn, reschedule or did i dream about being on the 11th?

@blainesch
Collaborator

@rapzo it was scheduled for the 11th originally but changed a few minutes after it was announced due to mothers day. Sorry about that! I hope you can still make it [:

@blainesch
Collaborator

Who's excited for tomorrow?!

@gwoo
Owner
@blainesch
Collaborator

Were all hanging out in #li3 on irc.freenode.net !! In the process of making a Trello board to help manage tasks!

If you need help deciding what to do head over to the Trello board, or pop into #li3 and we'll be glad to assign you something! [:

@rspenc29

So did anything ever happen with this? The documentation is still looking pretty lame.

@tmaiaroto
Owner

I have a branch with some documentation for MongoDB queries and such...Though it's not quite where I'd like it just yet. I've been super swamped with things, but seriously do want to get back to it. There's a few nuances with MongoDB and Lithium that I think are important to document. Especially you get into aggregation, replica sets, and so on. I do promise to get back to this, but I also feel like I failed to reach the level of documentation that I was personally seeking to provide on the matter. Sorry =(

@nateabele
Owner

@rspenc29 Yeah, we wrote a bunch of API docs that will be published once the online version of the docs is updated to 1.0 beta (soon, I promise).

@blainesch blainesch closed this
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.