Right Format for Documentation

Site Feedback
1

Continuing a conversation from
Using Open Hybrid as front end - #12 by Carsten

@Carsten and @V_Mohammed_Ibrahim
Maybe we can research a bit how other open source projects organizing their documentation.

Open Frameworks for example use the a git repository for the documentation and webpage similar then using it for code. I find this interesting, but what format will it have?

@marcteys I was remembering that you implemented some github/documentation in a wordpress version of the webpage. Can you tell us more about it?

Eventually I would like to bring the webpage back in to an easy editable and shareable format.
I am using adobe muse to get quick results, but I feel that this will reach its limits soon.
Wordpress was a good call and I would like to bring it back to it soon, so that we can work on it all together. Are there any other ideas?

In short:

  1. What is the best format and option for shared documentation?
  2. What is the best shareable and flexible platform for the webpage?
2
  1. I think some sort of wiki would do just fine. The structure requires some thought. Stuff like what sections and subsections to create. Once that is done it can be filled with content by the community.
3

I will try to locate the previous documentation file.

The documentation was a .markdown file parsed directly from Github. That’s the most easy way to create a simple collaborative document, that’s what openFrameworks and many others are doing. There are several on the fly markdown parsers such http://daux.io/ , https://documentup.com/jeromegn/documentup and others…

Read : Why You Should Use Markdown for Your API Documentation

2 Likes
4

The markdown , looks like a good and simple option to use for documentation

5

I like https://documentup.com/jeromegn/documentup.
It looks like it allows you to embed the markdown parser in to the webpage via javascript?

  1. It would allow us to use markdown to keep the webpage flexible for changes and github for collaborating.
  2. It probably would allow to include the javascript / html code in to the Adobe Muse page so that Muse can still be used for super flexible design changes.

Maybe some more pages from the webpage can be opened to that concept as well.

What do you guys think?

6

Ok I am taking that back. Its not implemented in javascript.

7

I found another documentation generator from markdown called

Its right in javascript,
however it has some issues with images.

Maybe http://daux.io/ is the better choice as it allows more flexibility.
I can just host it on like documentation.openhybrid.org or something like that.

1 Like
8

I researched all day today and yesterday and experimented a lot.
I found a good path to go.

I installed daux.io on a webserver and used github webhooks to synchronize the documentation folder.

I chose daux.io because it allows us to structure the documentation with folders and individual .md files.
This allows a more simple and shared workflow on the documentation.

The documentation is hosted here:
http://documentation.openhybrid.org

I will link it within the Webpage, once we have a good amount of documentation collected.

The responding github can be found here:

@V_Mohammed_Ibrahim @Carsten @KevinOrtman @marcteys Do you have interest to contribute? I can add you for write access to the repository.

1 Like
9

sure ! @valentin , i can put the existing FAQ in the FAQ section :smile:
and i guess the developer section is for the guidelines we discussed earlier ?

10

@V_Mohammed_Ibrahim what is your github account name, so that I can add you?

11

It is vmohammedibrahim
www.github.com/vmohammedibrahim

12

I was using flatdoc. I think everything will be fine as long as you can modify easily the .css. I used flatdoc because I have seen this doc made with it. But we can do the same with daux.io .

I found the previous doc : http://half4.com/pro/doc.zip . You’ll find the html/css and the current doc written in Markdown ! You can add me to the repo if you want

13

You can add me as well @valentin.

14

Flatdoc is amazing, because we can just host it all on a github page and its all generated in javascript. What I like specific about daux.io is, that the documentation is composed from many individual files and folders. This allows us an easier collaboration as different people can take the lead with different sections and work simultaneously without ever creating commit conflicts. How do you guys think about this benefit?

The look and feel can be easily manipulated via a css theme and page templates.