Documentation - Work in Progress


#1

Lets discuss the right structure for the documentation with this Topic.

The work in progress page is hosted here:
http://documentation.openhybrid.org

The responding github can be found/forked here:

The documentation structure is based on the folders and .md files within the folders.


#2

#3

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…


#4

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?


#5

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.


#6

I added the suggested structure and some other points that came to my mind. Let me know what you think.


#7

@valentin i have added a FAQ to the openhybrid FAQ file


#8

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?


#9

Yes , the heading is too large ,
i have added the second FAQ to the file , is there a way to add images to it ?


#10

Yes, take a look at this guide to markdown. It provides a short overview of the features.


#11

@Carsten @valentin i would suggest we do the documentation for the interface building and also for the existing interfaces first. what do you think?
i will be free after this week


#13

#14

@Carsten good work with the developers section
i have updated some other pages with basic info


#15

Thx, I just finished the Hardware Interfaces section. 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?


#16

yes, I will make some changes to it.


#17

I made a change to the theme. What do you think?


#18

Great! It’s way better.


#19

The documentation looks good now, :slightly_smiling:


#20

@valentin
Are there any portions of the documentation that you would like help with , my exams are over now :slightly_smiling:
i will also be working on the pi interface
will there be a link to the documentation page from www.openhybrid.org ?


#21

added a videos section to the doc and added links to all the videos here