Lets discuss the right structure for the documentation with this Topic.
The work in progress page is hosted here:
http://documentation.openhybrid.org 48
The responding github can be found/forked here:
The documentation structure is based on the folders and .md files within the folders.
Jan '16
Apr '16
pinned globally Jan '16
I reckon the documentation is supposed to document the beta_hardwareInterfaces branch already? Or should we rather create a corresponding branch for the documentation?
I would suggest to put a section “Hardware Interfaces” under “For developers” where we can describe the hardware interfaces API and show how to implement a new hardware interface and emphasize the design guidelines again.
Additionally I would suggest a categorie “Hardware Interfaces” with sections for each hardware interface under “Open Hybrid” where we describe the usage of the specific hardware interfaces.
And I think a categorie “Philosophy” or “About” or something like that where we can put the basic philosophy / guidelines stuff which can currently be found under “About” on the website would be good. I’m not sure if we should put it under “Getting started” or create a new categorie…
yes @valentin i think @Carsten suggestion would make it more understandable and organized
@carsten the documentation is for both the branches together , we could just add the doc for beta interfaces in a “hardware interfaces” section under the developer category as you suggested , what do you think?
Yes thats a good idea.
Philosophy might sound a bit to theoretically and About is not really matching it.
What do you think about Design Guidelines? It would tell more about the intention for the About section.
It should reflect the DNA for how to design Hybrid Objects.
I believe that we can write the entire documentation based on the latest work (beta_hardwareInterfaces) and ignore older work. The beta_hardwareInterfaces branch will become the main branch once we have debugged it on all relevant systems. And then eventually it will be updated in to the Arduino Image.
Probably by that time we do have the documentation ready as well.
I added the suggested structure and some other points that came to my mind. Let me know what you think.
@valentin i have added a FAQ to the openhybrid FAQ file
I think you should add that you are talking about the arduino Yun HW Interface @V_Mohammed_Ibrahim . Maybe we should introduce categories for each hardware interface and a General categorie under FAQ->OpenHybrid, what do you think? Otherwise people using other interfaces might get confused. And we should think about a layout to increase readability.
UPDATE:
I edited your commit @V_Mohammed_Ibrahim to provide a suggestion for formatting the FAQ’s. It’s far from perfect. The heading is too large in my opinion. We should either use a second or third level heading or @valentin could change the corresponding css, what do you think? I want to emphasize that this is just a first suggestion and that we should discuss the FAQ layout more. For example we should discuss how to format function calls. Just make them bold, or format as inline code?
Yes , the heading is too large ,
i have added the second FAQ to the file , is there a way to add images to it ?
Yes, take a look at this guide 5 to markdown. It provides a short overview of the features.
unpinned Feb '16
@Carsten good work with the developers section
i have updated some other pages with basic info
Thx, I just finished the Hardware Interfaces section 7. I hope it’s clear enough.
@valentin we might want to change the theme or create a new one. The inline code is barely readable because it is grey on a whitish background and I don’t really like the format/size of headings. What do you think?
yes, I will make some changes to it.
Great! It’s way better.
The documentation looks good now, 
@valentin
Are there any portions of the documentation that you would like help with , my exams are over now
i will also be working on the pi interface
will there be a link to the documentation page from www.openhybrid.org 1 ?
added a videos section to the doc and added links to all the videos here
I’m not 100% sure that a videos section in the documentation is a good idea. First of all it is my understanding that the documentation is supposed to help users/developers use/develop stuff. Videos by random users which only show what they have implemented don’t help with that. Tutorial videos on the other hand can be very useful.
Secondly it will be quite difficult to maintain that videos section because the regular user doesn’t have the rights to alter the contents of the documentation. So to add a new video the user would have to create a Pull Request which someone else then has to approve. → Complicated workflow for such a simple thing.
All in all I think that videos showcasing user projects should rather be published here in the forum where it is very easy for users to post such videos than in the documentation.
It’s worth discussing 
I need to figure out how to add a blog to the webpage.
Might be a project for the summer. We need to switch back to wordpress. :-D:
Posting all the videos is definitely something for a blog
@Carsten I see your point , I had only thought of letting people know of your difff things people had tried doing with it
@valentin yea a blog /videos (media) page on openhybrid.org would be nice to showcase them
@Carsten we will keep the videos section in documentation for now and then move it to the webpage blog when it gets finished , what do you think ?
@valentin could you check if the documentation site is down , it doesn’t load
@valentin
For the redesign of the page , it would be good if it had a develop section which covers creating of hardware interfaces etc.
What did you have in mind for a separate engineers, designers section etc ?
For newcomers it would be best if we could provide more detailed explanation of how things work
we could for example give more explained description on using the arduino functions etc.