search

Iridescent-CM / attendance

A stupid simple app for program attendance-taking
1 stars 1 forks source link

Documentation #1

Open stenington opened 9 years ago

stenington commented 9 years ago

While I usually forgo detailed docs in favor of readable code, in this case I think users of the system would benefit from some help on the interface, and an as-non-techical-as-possible setup guide would be good.

stenington commented 9 years ago

@toolness or @christensenep either of you know what django's admindocs looks like?

ghost commented 9 years ago

I haven't used it myself, but it seem like it would be helpful. It is oddly difficult to find any actual examples of what the end result looks like, though.

toolness commented 9 years ago

Yeah, I have busted up admindocs for the Hive directory, but I've found that they're really most useful for template designers and developers rather than for administrators of the system, IMO. Here are some screenshots from the admindocs of the Hive Directory to give you an idea...

This is the front page of the admindocs:

docs_frontpage

If you click on the "tags" link, you get this:

docs_templatetags

If you click on the "views" link, you get this:

docs_view

So yeah, it is pretty technical. Likely useful to onboarding new designers/developers, but not so much new administrators.

stenington commented 9 years ago

Ok, thanks! I think we need another more user-focused doc solution then.

toolness commented 9 years ago

Let me know what you decide on! I've been looking for a similar solution myself. Right now I basically just have a discourse thread where I post little guides and answer people's questions.

stenington commented 9 years ago

Hmm that's actually kind of nice idea if it might let users sort of "crowd-source" guides to help each other out.

stenington commented 9 years ago

Uh, but at the very least a starting point here would be good, if not a completely complete, addresses-everything-you-could-imagine sort of thing.

toolness commented 9 years ago

Yeah, I basically just made a new category in our discourse called "Hive Directory" and added a few pinned threads:

Aside from that, I also welcome people to ask questions and make suggestions etc. in the Hive Directory category itself. People who are super invested in the directory can then subscribe to email notifications for the whole category if they want.

stenington commented 9 years ago

@toolness I'm curious what kind of level of effort it takes to run a discourse instance?

toolness commented 9 years ago

If you bust it up with the ol' Docker, which they have great instructions for, you can get it up and running in 30 minutes or less. And I believe that the deployment even self-updates itself, which is crazy cool... If not, it at least pokes you to upgrade whenever it detects that there's a new version, a la Wordpress, which is nice.

The big "cost" for DIscourse IMO isn't time but money... It wants a relatively beefy machine to run on: 1 GB RAM minimum, which on Digital Ocean costs $10/month. So it's not really a lightweight thing you can just throw up on a free Heroku instance.

ghost commented 9 years ago

I actually have some experience running Discourse (nothing that went to production, but I've run a staging version for an addon I was building for it), so if you want me to take point on that, I'd be happy to. Assuming we feel like going that route, of course.

toolness commented 9 years ago

Discourse rocks! The only two downsides I can think of are:

Other than that it is the most awesome awesome thing ever. And the posts support Markdown and basic HTML so anyone who's familiar with GitHub will feel right at home!

toolness commented 9 years ago

However, I am also a forum junkie so my views may be biased.