Documentation project?


(Paul Mackay) #1

What does anyone think about the idea of creating a more formal documentation site such as something hosted on https://readthedocs.org/, or perhaps built using Gitbook? As someone who would like to learn more, there is lots of info in various places but it can be hard to find the right bits. A proper docs project could allow more focussed docs to be built up, have issues raised against it, etc. Just a suggestion and happy to have it flamed down if it wouldnt be a good fit :slight_smile:


(Thomas Kalka) #2

Ha, that would be good, once we get clear ideas about how things should go …

In the meantime we should start to delete a lot of content here.

In my opinion the semantic wiki (http://mmm.3oe.de) could be a place, to gather information about used technological stacks, licenses and more general principles of data exchange, tools etc …


(Jon Richter) #3

There were early approaches of writing documentation together at https://wiki.14mmm.org or http://wiki.transformap.co. They never lift off. Given the technology, I am very much in favour of MarkDown capable wikis, but can also live without.

I am rejecting the Mediawiki software family for its user interface (its 2015 after all), but could always live with a dokuwiki instance.

If looking at the diversity of opinions floating around the TransforMap scape, I think now we are one of the first communities which could directly leapfrog the old Neutral-Point-of-View wikis and step into Federated Wiki space. Collaborations on pods like http://goals.pods.wiki.org takes a few months to get accustomed to, but would reflect the internal independence we want to allow our actors.

I have also thought of static site generators from MarkDown files (like http://dokku.viewdocs.io/dokku/installation/), GitHub/-Lab/Gogs git wikis and http://realms.io/.
Right now most of our wiki content lives in this Discourse, but is not properly highlighted nor seperated from the discussions.


(Thomas Kalka) #4

Ha, always opting for “programmers only” solutions …


(Jon Richter) #5

In a sense, we’re already talking about writing a TransforMap manual since more than a year. Using a git-based or similar workflow is desireable, as one wants to be able to represent different versions of reality at the same time.

Please tell me how the interfaces of

are programmers-only?

Addendum:

For Federated Wiki, there is also a reader available at http://wikity.net/ (git). The ideal solution would be a markdown-capable etherwiki like Hackpad. I am currently reinvestigating deployment options, as previous attempts failed.

Istepanov’s image finally worked, but didn’t have working email support on localhost. But https://github.com/spikeekips/hackpad/commits/master looks quite promising.


(Michael Maier) #6

Maybe we should add a “wiki” tag to them?


(Jon Richter) #7

We had this tag already. But tags are currently still disabled. Also is the Discourse interface a bit too overloaded for simple wiki workflows.

I’d imagine https://github.com/claudioc/jingo (wiki.transformap.co) as a base with http://prosemirror.net/ would give quite a good figure.

I like the approach to mix Pads and Wikis to reduce complexity.


(Paul Mackay) #8

@almereyda are you suggesting Jingo + Prose as a solution or Hackpad? I could see Jingo offering a good result. Not sure if Hackpad can produce quite the same effect in terms of a canonical docs site.


(Jon Richter) #9

Yes, I believe a simple integration of the real-time capabilities of Prosemirror into Jingo would turn it into a very interface to the Markdown git repo synced in the background to wherever we want. Of course we can also adapt its CSS to suit our style.

I am just tempted by Hackpad due to the already integrated features it comes with. Especially the E-Mail notifications on changes are very interesting.


(Paul Mackay) #10

If Jingo uses a github repo people could watch that if desirable?


(Jon Richter) #11

3 posts were split to a new topic: Meeting minutes and other real-time notes


(Jon Richter) #14

Yes, you could even push to the GitHub repo and see your changes live later. Also see:

But it is missing a Media Library, Breadcrumbs and all the luxury features known from doku- or Mediawiki.


(Jon Richter) #15

4 posts were split to a new topic: notes.transformap.co


(Jon Richter) #16

Due to popular demand about clarity of what TransforMap is and intends to be, I am currently preparing an overview of approaches to identify and to reintroduce diverse narratives involved in its process.

  1. Communication Infrastructure and (in)formal Commons

This may eventually lead to some updates on wiki.transformap.co.


Some parts of this documentation effort are broken out into https://notes.transformap.co/Documentation-Project-QVnpBghK5Jg


necessary adaptation to reinforce the commoning process
Geodata storage evaluation
Hackpad - Meeting minutes and other real-time notes
Mailing lists
(Jon Richter) #17

2 posts were merged into an existing topic: Hackpad - Meeting minutes and other real-time notes


(Josef Kreitmayer) #18

A post was merged into an existing topic: Hackpad - Meeting minutes and other real-time notes


(Jon Richter) #19

I have just restarted wiki.transformap.co as a federated wiki farm with an initial topology. If we had a plugin to auto-generate subdomain wikis for participation to claimed pods, and if the Persona dependency can be sufficiently overcome, this should allow for multiple points of views on what TransforMap is.

Even though a community process is something different than just setting up a web service, as users will have to know how to participate, this can be an interesting challange to the wiki developers, too.