|Call for Documentation Cleanup Feedback!||Sean Tilley||2/18/12 2:50 PM|
Something that we've been wanting to double down on is our
documentation on the wiki. We want to clean up the wiki to make things
more relevant, better organized, and more applicable to the current
codebase. In order to do that, we want to give community developers,
podmins, and enthusiasts the chance to speak up and give us some
feedback on the current state of our documentation. This is an
opportunity for us to better organize things to suit YOUR needs.
Currently, a basic brainstorming page is up on the wiki, you can find
it here: https://github.com/diaspora/diaspora/wiki/Documentation-Cleanup-Brainstorming
It'd really be great to hear everyone's thoughts on this, so that we
can make our information as accessible as possible.
|Re: [D*] Call for Documentation Cleanup Feedback!||Roger That||2/19/12 3:23 AM|
here are some thoughts of mine:
- What do you feel that the documentation is missing?
beside what you mentioned: some clear areas like
i think useroriented-docu can be quite fancy with links to
and if you'd use the official wiki for dev-documentation
maybe thats better answered by diaspora-inc officials and devs?
- What snags have you run into in trying to run your own pod, and what
the install-docu worked fine for me, but i'm a little advanced,
but there's no docu on what to do after setting up a pod and how to get
there's nothing like a customization-howto, that would be nice, just a
outdated docu ;-)
for technical/devstuff its just fine (can it connect to #commits and
|Re: [D*] Call for Documentation Cleanup Feedback!||elf Pavlik||2/19/12 3:48 AM|
Excerpts from Roger That's message of 2012-02-19 11:23:34 +0000:
while ago i just stubbed this page:
which links to related thread on mailing list
i just started playing with customizing pod i use, so far simple modifications i've made:
i also want to start theming it differently and customizing various views... would really like to come up with some sane workflow for customizing which makes it easy to still pull from 'upstream'
|Re: Call for Documentation Cleanup Feedback!||Raven24||2/19/12 9:13 AM|
In my opinion everything we can do to improve the documentation
depends on the underlying software we use for it. In our case this is
the wiki functionality provided by Github. It is not bad, as Markdown
is easy to understand and the pages can be edited by anyone with a
But from what I have noticed the amount of information has just grown
too big for the limited structural features the Github wiki provides.
What I really miss are categories and templates like they exist in
Currently we have no way of finding orphaned pages or pages where the
date of the last edit highly suggests the contents are out of date.
(At least none that I know of).
We should be able to categorize all the pages about dev stuff, end
user infos or pod adminstration etc. for the target groups to have a
list of all related information.
It would be very useful to be able to include a template saying this
information is out of date that also puts the page into a "out-of-
date" maintenance category, leaving the people who actually can
document technical stuff with a list of pages that need an update,
while people looking for the information are notified of the status/
correctness of the page they just opened. Or the advanced method would
be to let a bot flag all pages in the "federation" category out-of-
date because there was a change in the underlying code, for example.
I have seen a few MediaWiki installations about Diaspora out in the
wild, maybe they could provide some insight about their experiences...
http://wiki.spored.de - german
Florian // rav...@pod.fulll.name
|Re: [D*] Call for Documentation Cleanup Feedback!||Roger That||2/19/12 4:54 AM|
thanx, nice read
|Re: [D*] Re: Call for Documentation Cleanup Feedback!||Tom Scott||2/19/12 10:46 AM|
Since github is where developers mostly come together, maybe we could move all non-developer documentation to http://doc.joindiaspora.com and keep installation instructions, setup/maintenance documentation and the contribution checklist on github for developers to peruse. Perhaps we could keep federation specs on http://api.joindiaspora.com
|Re: [D*] Re: Call for Documentation Cleanup Feedback!||Richard Price||2/19/12 6:57 PM|
Installation instructions should be included with non-developer
Also, since the amount of information is the perceived problem, one is
to ask if the bulk of the WIKI is "non-developer documentation". If not
proposed split would not have a high impact on the perceived problem.
|Re: [D*] Re: Call for Documentation Cleanup Feedback!||rek2||2/19/12 7:40 PM|
we should add a help link on top of each diaspora page or in the user menu...
|Re: [D*] Call for Documentation Cleanup Feedback!||Tom Scott||2/20/12 7:34 AM|
I believe it is.
We're looking at seven major sections here:
- General Resources
I'm basically talking about cutting out everything that isn't "Developer Resources" and possibly "Contributor Resources" from the GitHub Wiki, and moving that to http://doc.joindiaspora.com, which will be a MediaWiki install or something equal to its feature set. The only people who will have to go to GitHub when this goes beta are developers who wish to contribute. So all of these other categories could be feasibly moved off of GitHub and into our self-hosted wiki. If everyone feels it would be better we could even move developer documentation off of GitHub. One thing that is cool about the GitHub Wiki is Markdown, but is there no way to allow for Markdown posting in MediaWiki or something?
For the record, I also feel as though "Mobile/Third-party App Resources" should be completely omitted from the wiki. These apps are not part of the Diaspora project, they are 3rd-party apps developed by private teams, much like TweetBot's relationship to Twitter, and therefore there is no need for us to allocate resources to them and further clutter up the documentation. There are two reasons for this.
First, I believe this project, and this list, has become subject to diversions from all kinds of people who wish to inject their own agenda into DIASPORA*, and we must constantly be vigilant in moving forward with the goals of the DIASPORA* project, and not the Linked Data project or the hAtom project or each developer's own pet projects. There's a reason we all came together and began contributing to this thing, right? The mobile apps are NOT priority 1 for this project, getting the next generation of Federation Protocol and the beta of the DIASPORA* app up there and easy to install IS.
Second, all of these projects have their own GitHub repos with their own wikis, issue trackers, and private discussions. I feel as though planning will naturally happen on those sources, and there's no reason to maintain planning discussions in two places at once. As much as I'm supportive of welcoming them into the development and planning for the mother project, I don't feel as though the DIASPORA* organization as a whole needs to be overseeing the iOS/Android app development process. DIASPORA*'s API should be coherent enough so that any developer can implement the client on their platform of choice, and developers who wish to implement the client shouldn't need to be paying attention to this list to properly make a client that talks to our API.
|Re: Call for Documentation Cleanup Feedback!||Steven Hancock||3/3/12 11:05 PM|
One thing I'd love to see, especially since joindiaspora is deployed
is a step-by-step guide to deploying on Heroku. I've gotten as far as
a pod online and logging in, but federation doesn't work and if I try
for (for example) my diasp.org account I get errors from the Resque
I'm assuming that's a Postgresql issue (and I'm considering testing
theory with a dotcloud-hosted Mysql database), but if that's the case
be nice to see some docs that tell me that up front. :)
> it here:https://github.com/diaspora/diaspora/wiki/Documentation-Cleanup-Brain...
|Re: [D*] Call for Documentation Cleanup Feedback!||Sarah Mei||3/4/12 11:59 AM|
That's a great idea. joindiaspora's setup is a little different from the typical Heroku setup, because we run a MySQL database on RDS instead of using the built-in PostgreSQL. Mostly that's because the data migration would have taken forever.
But we should definitely write up a guide. Can you put what you've done on the wiki as a starting point?
|Re: [D*] Call for Documentation Cleanup Feedback!||Steven Hancock||3/4/12 9:43 PM|
I'm actually going to start over from scratch within the next couple days, using a dotcloud-hosted myqsl database instead of Heroku's postgresql because I think that's the root of my federation problem. I'd use RDS, but I'm not eligable for Amazon's free tier and I'm trying to get started with as little out of pocket costs as possible (I have a beta account with dotcloud, so using one of my 4 free services there is no problem). Once I get started again, I'd be happy to document the process and put something up on the wiki :)
|Re: [D*] Call for Documentation Cleanup Feedback!||Steven Hancock||3/9/12 6:45 PM|
Just to give an update, I do still plan on setting up a pod on Heroku and writing something up for the wiki, but unfortunately I came down with what I can only assume was some kind of stomach bug or mild food poisoning, so I haven't gotten around to that (or much of anything else) this week.. today was the first time I've even felt like moving all week lol
|Re: [D*] Call for Documentation Cleanup Feedback!||Steven Hancock||3/12/12 9:54 PM|
I have my pod on Heroku mostly working and I can see users from other pods when I search for them, so I've gone ahead and written up (mostly from memory) a Heroku deployment guide. https://github.com/diaspora/diaspora/wiki/Installing-on-heroku
I made sure to include contact info at the top, at least until we're sure it's correct and complete, so people can come to me with any questions they might have. If I've left anything out, or if there's a better way, feel free to contact me and let me know (or just edit the page). :)
|Re: [D*] Call for Documentation Cleanup Feedback!||Maxwell Salzberg||3/19/12 8:14 PM|
This is really awesome. I am extremely exhausted at this point in time, but I wanted to thank you for putting this together. You do a bunch of clever things I wouldn't have thought of doing to make it work.
I want to sync up at some point to see how we can take our knowledge, get it on the wiki, and see if we cant make this whole thing much easier.
Dan, Dennis and I are actually going to pay Heroku a old visit sometime soon, in hopes to get tips and tricks to make this even easier.
|Re: Call for Documentation Cleanup Feedback!||Steven Hancock||3/21/12 9:43 PM|
Thanks, really the most clever thing I did that I can think of was
firing off the Resque worker in Unicorn's before_fork and I have to
admit I stole that from a blog post that I read about a year ago (I
think googling "concurrency on heroku" or "resque on heroku" should
bring it up on the first page). That needs a little work too, I notice
when I look at my resque-web interface I can see the old stale workers
from previous pushes.. and I know they aren't still running (Heroku
has a process limit, I don't know what it is, but I know you can't run
30 in one dyno) so I need to make Resque clean up after itself a
little better. :)