search

WardCunningham / Smallest-Federated-Wiki

This wiki innovates by: 1. federated sharing, 2. drag refactoring and 3. data visualization.
http://wardcunningham.github.com/
GNU General Public License v2.0
1.21k stars 178 forks source link

Documentation #354

Open paul90 opened 11 years ago

paul90 commented 11 years ago

While considering the best location to add the windows specific steps for getting the server up and running (Sinatra version initially), I am struck that the documentation contains some duplication, maybe some inconsistency, and is scattered over a number of locations - the various ReadMe.md (the ones in root and /server/sinatra both having something to say), and the Hosting and Installation Guide page in the GitHub wiki (though that page does not appear to be directly linked to).

I wonder if it is time rationalize the documentation, and if so where it would be best hosted.

WardCunningham commented 11 years ago

Oops. Sorry to have ignored this observation. Yes, you are surely right. GitHub has the advantage that it is more reliably up than any individual SFW server. The GitHub wiki has the advantage that it doesn't take a pull request to share experience. But there should be a clear story for how to get going in every environment and we don't have that yet. Here would be one suggestion:

Main page explains were to find all documentation.

Other md pages in the code base contain advice for coders.

GitHub wiki has user curate advice on getting started on diverse platforms.

Fed.wiki.org has how-to documentation.

Project history and retrospectives are somewhere, maybe ward.fed.wiki.org??

WardCunningham commented 11 years ago

Another thing I should explain: I've been experimenting with federated wiki farms that support workgroups that are separated from the internet. This is an outlier usecase for sure. But it does raise to me the question of how one hosting a farm could insert specialized instructions for first-time users that engineer a sensible experience.

paul90 commented 11 years ago

Regarding the workgroup separated from the internet while it is something of an outlier, needing to be self contained. I can see this just being one end of a spectrum of connectivity (both internet and federation) - though how many points along that spectrum will see use?

almereyda commented 11 years ago

If you are satisfied with my latest posts/issues I'd offer my help to volunteer with the documentation. That would mean I'd revisit https://github.com/WardCunningham/Smallest-Federated-Wiki/wiki/_pages, turn it into a specification / reference repository and tagged the issues in the repositories according to their topics.

Maybe it'd be clever to do so after it's been decided how the project repositories are organized in the future. Preparations have already been done in https://github.com/WardCunningham/Smallest-Federated-Wiki/issues/402.

Also if the codebase would have been organized in an organization I wouldn't have had to fork the whole project just to issue a little change as in https://github.com/WardCunningham/Smallest-Federated-Wiki/issues/88

Main page explains were to find all documentation. Other md pages in the code base contain advice for coders. GitHub wiki has user curate advice on getting started on diverse platforms. Fed.wiki.org has how-to documentation. Project history and retrospectives are somewhere, maybe ward.fed.wiki.org??

I have the intuition that this is a little too cluttered, to be frank. Maybe one can simplify this even further? I mean, I'm working on the wiki for months now and I'm still finding new links to important pages that explain an issue, an idea or a specification on places that I didn't think of before. But I admint the red line is also constantly changing as the project develops (with the different repos, etc.) and the used, existing systems don't inherit the same flexibility as the Wiki does.

Still, for me it is not clear where to find specifications / recommendations / conventions / references. I'm always looking in the GitHub wiki for this, but don't find everything I'm interested into.

Also, there's another documentation that's hidden in the code's comments to be made alive with docco. https://github.com/WardCunningham/Smallest-Federated-Wiki/issues/240 is an example of someone not finding it. Maybe one regenerates those docs with each npm build and put's them on a gh-page? That could also be a place - the place? - for a "end-user friendly" landing page - i.e. wiki.github.io (or a custom domain name)? This could also take the project history and retrospectives, if appropriate.

This would also be possible with the organization. My target is only to simplify the documentation. Please correct me if my ambitions head in the wrong directions, as I'm always not sure if I demand too much, imagine without knowing the right way or express interests that your experiencies have proven disadvantageous.

(Last post for today. Happy.)

WardCunningham commented 11 years ago

I see that there has been much conversation. I will catch up soon.