Call for Documentation Cleanup Feedback!
Sean Tilley
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.
<3
-Sean
Roger That
Hello Sean,
here are some thoughts of mine:
- What do you feel that the documentation is missing?
beside what you mentioned: some clear areas like
- User
- Podmin
- Dev
- Get involved (as user/podmin/dev)
i think useroriented-docu can be quite fancy with links to
video-tutorials, articles form other sources etc, while the
tech-oriented docu is ok for me in its current form.
and if you'd use the official wiki for dev-documentation
other devs could easily step in.
- Have you noticed any documentation that isn't up to date, and is no
longer correct?
maybe thats better answered by diaspora-inc officials and devs?
if you change and improve things in the core or the ui it would
be the usual workflow to update the documents.
- What snags have you run into in trying to run your own pod, and what
would you like documented about those problems?
the install-docu worked fine for me, but i'm a little advanced,
compared to
a normal user. imho its not that complicated as many users cry out,
esp. those
who rented some webspace and are able to install wordpress/friendica.
and i think it's right to stick with the ssl-paradigm.
but there's no docu on what to do after setting up a pod and how to get
it
running and connected. and nothing about the technical requirements
for podmins for lets say 10/1000/10.000 expectred users.
i'm working on this now, but it takes some time to get the experiences.
there's nothing like a customization-howto, that would be nice, just a
short
intro for people not so familiar with rails.
- Is there anything in the documentation that just plain doesn't make
sense to you?
outdated docu ;-)
- Do you feel that the GitHub wiki serves its purpose well, or do you
think a different solution would be
necessary in the future? (MediaWiki, MoinMoin, Tiddlywiki, etc.)
for technical/devstuff its just fine (can it connect to #commits and
#bugfixes
like trac?), for the end-users who whish to have an overview it might
be better
to convince them with eyecandy && videos ;-)
regards,
roger
elf Pavlik
> there's nothing like a customization-howto, that would be nice, just a
> short
> intro for people not so familiar with rails.
https://github.com/diaspora/diaspora/wiki/Customizing-a-pod
which links to related thread on mailing list
i just started playing with customizing pod i use, so far simple modifications i've made:
* allowing '-' and '.' in usernames (as I use perpetual-tripper)
* added route to serve profiles from '/:username' (since I use https://wwelves.org/perpetual-tripper) as my homepage
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'
cheers!
=)
~ elf pavlik ~
Raven24
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
Github account.
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
MediaWiki.
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
http://diasporatest.com
cheers,
Florian // rav...@pod.fulll.name
Roger That
thanx, nice read
Tom Scott
-T
> --
> You received this message because you are subscribed to the Google Groups "diaspora-dev" group.
> To post to this group, send email to diaspo...@googlegroups.com.
> To unsubscribe from this group, send email to diaspora-dev...@googlegroups.com.
> For more options, visit this group at http://groups.google.com/group/diaspora-dev?hl=en.
>
Richard Price
documentation.
Also, since the amount of information is the perceived problem, one is
forced
to ask if the bulk of the WIKI is "non-developer documentation". If not
then the
proposed split would not have a high impact on the perceived problem.
rek2
Installation instructions should be included with non-developer documentation.
Also, since the amount of information is the perceived problem, one is forced
to ask if the bulk of the WIKI is "non-developer documentation". If not then the
proposed split would not have a high impact on the perceived problem.
On 02/19/2012 12:46 PM, Tom Scott wrote:
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
-T
To unsubscribe from this group, send email to diaspora-dev+unsubscribe@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/diaspora-dev?hl=en.
--
You received this message because you are subscribed to the Google Groups "diaspora-dev" group.
To post to this group, send email to diaspo...@googlegroups.com.
To unsubscribe from this group, send email to diaspora-dev+unsubscribe@googlegroups.com.
Tom Scott
We're looking at seven major sections here:
- General Resources
- Developer Resources
- Mobile/Third-party App Resources
- Contributor Resources
- Pod Maintainer Resources
- Community Resources
- Other 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.
- T
stevenh512
there,
is a step-by-step guide to deploying on Heroku. I've gotten as far as
getting
a pod online and logging in, but federation doesn't work and if I try
to search
for (for example) my diasp.org account I get errors from the Resque
worker.
I'm assuming that's a Postgresql issue (and I'm considering testing
that
theory with a dotcloud-hosted Mysql database), but if that's the case
it would
be nice to see some docs that tell me that up front. :)
On Feb 18, 2:50 pm, Sean Tilley <s...@joindiaspora.com> wrote:
> Hi guys,
>
> 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
Sarah Mei
But we should definitely write up a guide. Can you put what you've done on the wiki as a starting point?
Steven Hancock
Steven Hancock
Steven Hancock
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). :)
Maxwell Salzberg
Thank you,
--
You received this message because you are subscribed to the Google Groups "diaspora-dev" group.
To view this discussion on the web visit https://groups.google.com/d/msg/diaspora-dev/-/Ae6QL2JyReIJ.
Steven Hancock
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. :)
On Mar 19, 8:14 pm, Maxwell Salzberg <maxw...@joindiaspora.com> wrote:
> Steven,
>
> 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.
>
> Thank you,
>
> Maxwell
>