[SOLVED] Request to complete Documents>Using SOFA>Basic Components

[MegaMind]

Hi as a new user it is impossible to get going without knowing how to use the existing components and creating/editing them. Please increase the priority to complete the section at Documents>Using SOFA>Basic Components.

I recommend creating a wiki style section for the website that will be used for each component. There is a great deal of info needed for each component and right now there is only the code and the auto generated dOxygen. From the start coders can use it for requirements and then whomever is assigned to build the component should edit the page to fill out details needed for each component. Users then can read what is required for each component and very useful tricks and tips that can save a lot of headaches and even head off users abandoning use.

I would also recommend a commenting section to be activated for each component so that users can share info. Question & Answer type along with general comments and tips.

[Guillaume]

Hi Andrey,

Improving the documentation is an everyday task for the SOFA Consortium. We (Hugo and me) are working to make it clear and easy to contribute.
We decided to avoid having a 3 parts doc (website + wiki + doxygen) because it is harder to maintain and has duplicates risks (particularly between the website doc and the wiki).

Instead, we chose to setup a 2 parts doc (website + doxygen) with an editable website doc based on a Markdown repository (behaving like a wiki but nicely integrated to the website).
This repository is completely open to contributions: you can add/edit files/folders and propose what you think would be great with a pull request.
It would be possible to have one page per component but wouldn’t it be better to have those tips & tricks in the Doxygen ?

Concerning the comments section, you are right. It was removed when we migrated to the Markdown system. I will reopen it 😉

Best regards,
Guillaume.

[Hugo]

Dear Andrey,

Guillaume is right, documentation is an everyday task among many others for the SOFA Consortium.

I wanted to stress that it exists a documentation article about how create a component in SOFA.
Does this article fit your expectations ?
As Guillaume mentioned, we would be very grateful if you would be willing to contribute to the SOFA documentation.

Best wishes,

Hugo

[MegaMind]

It sounds like it’s just Guillaume and Hugo doing everything which seems odd and unfair to you poor guys. Get some help. Students/interns are great to abuse. Apply for Google’s summer of code and others are great. Anyway you guys are doing a great job so keep it up.

“We decided to avoid having a 3 parts doc (website + wiki + doxygen) because it is harder to maintain and has duplicates risks (particularly between the website doc and the wiki).”
Yes and all software devs face this problem. But what you get is a static website and a doc that nobody knows how to read except for the original coders and even they are unsure because they forget. This why a living doc that all the developers, managers, users, etc use and rely on in step with the advancement of the codebase is more useful in the end. So it will not be just up to two guys to update documentation because all involved are looking to that doc and updating it. Getting the team on board to do it the trick of course but once done it goes smooth because that is what people want; most of the info they need in one place. Scripts can be used to pull info from dOxygen, Trello, etc that can really help to automate the process.

“It would be possible to have one page per component but wouldn’t it be better to have those tips & tricks in the Doxygen ?”
No. For a user hunting down this info in the dOxygen that is in a useful form never works out. It would be nice in theory though. Best to have it in the wiki made by the coder and also in the runSOFA gui component section. Every option needs a help flyout or link. Otherwise you get what it is now and you have options that are a number entry with no idea of what can be used.

[Author]

Posts