Dear Genode,
It would be beneficial to keep a user specific wiki, i meant not the actual documentation that is provided in the Genode home, but some newbie guide to getting started. Say setting up network interface , how to. etc. Well, though source tree is well organised , it can be a lost world for a newbie. So, a wiki from the genode domain would be of great help. What are your views ? Seems like future Google Summer of Code students can benefit from this.
Hello Althaf,
On Sun, Mar 04, 2012 at 12:35:22PM +0530, Althaf wrote:
It would be beneficial to keep a user specific wiki, i meant not the actual documentation that is provided in the Genode home, but some newbie guide to getting started. Say setting up network interface , how to. etc. Well, though source tree is well organised , it can be a lost world for a newbie. So, a wiki from the genode domain would be of great help. What are your views ? Seems like future Google Summer of Code students can benefit from this.
We had a Wiki for Genode on http://genode.org/ for the last years, but besides one or two small community contributions all contents came from Genode Labs. Beyond this limited feedback, we spent significant efforts to maintain the Wiki and additionally the sames contents in the source tree because this is what users of Genode have at hand. During the transfer of the contents of our website from Plone to static HTML, we skipped the Wiki in favour of the documentation bundled with the sources.
We concentrate our development process (and this includes documentation/howtos/...) at Git and GitHub. Therefore, the complete docs can be cloned with the sources, issues for missing pieces or shortcomings can be reported, discussed, and marked as "doc"-specific. So, contributions will finally imply a pull request or patch extracted from the issue discussion.
I personally do not see significant advantages of a Wiki over this process, but more efforts in regard to moderation of another communication channel. But, I'm open for other opinions and ideas.
Greets
Hello Althaf,
It would be beneficial to keep a user specific wiki, i meant not the actual documentation that is provided in the Genode home, but some newbie guide to getting started. Say setting up network interface , how to. etc. Well, though source tree is well organised , it can be a
I think that these topics should ultimately be covered by our official documentation. Your criticism is valid for sure. But I think the problem is not so much the technical question of which tool to use (Wiki versus Git repository) but rather our lacking ability to put ourselves in a true beginner's position. The top-level 'README' and the 'doc/getting_started.txt' are our current attempt to do so - apparently with limited success. I would be very happy about true beginners to suggest improvements regarding these documents. I hope that thanks to GitHub, the bar for beginners to suggest improvements is low enough. I'm positive about it, taking our experience of the past weeks as some kind of empirical evidence. Your contributions are a good example. .-)
With regard to providing working step-by-step instructions, I think that the concept of our run scripts is principally well suited for this purpose as each of those scripts illustrates the steps needed to integrate a certain component in a setup of low complexity. Because such scripts are executable, maintaining their consistency with the actual system is easy. If we provided a bunch of "howto" documents instead, we would have a hard time to ensure consistency. Inconsistent or misleading documentation, however, would be worse than having a no documentation.
Cheers Norman
On 5 March 2012 19:02, Christian Helmuth <christian.helmuth@...1...> wrote:
Hello Althaf,
On Sun, Mar 04, 2012 at 12:35:22PM +0530, Althaf wrote:
It would be beneficial to keep a user specific wiki, i meant not the actual documentation that is provided in the Genode home, but some newbie guide to getting started. Say setting up network interface , how to. etc. Well, though source tree is well organised , it can be a lost world for a newbie. So, a wiki from the genode domain would be of great help. What are your views ? Seems like future Google Summer of Code students can benefit from this.
We had a Wiki for Genode on http://genode.org/ for the last years, but besides one or two small community contributions all contents came from Genode Labs. Beyond this limited feedback, we spent significant efforts to maintain the Wiki and additionally the sames contents in the source tree because this is what users of Genode have at hand. During the transfer of the contents of our website from Plone to static HTML, we skipped the Wiki in favour of the documentation bundled with the sources.
Ah, yes, i understand this issue now, making it consistent across various versions would be a pain.
Either way, i would recommend a new directory entry to /doc/ , that would be /doc/contrib , which will contain user contributed documentations. And should be with a Post Script in README file
" Genode labs doesn't monitor the consistency and validity of the documents provided here, these are contribute by the community for educational purpose "
. The top-level 'README' and the 'doc/getting_started.txt' are our current attempt to do so - apparently with limited success. I would be very happy about true beginners to suggest improvements regarding these documents. I hope that thanks to GitHub, the bar for beginners to suggest improvements is low enough. I'm positive about it, taking our experience of the past weeks as some kind of empirical evidence. Your contributions are a good example. .-)
Yea, obviously, i do get lost in GIT at times. :D
With regard to providing working step-by-step instructions, I think that the concept of our run scripts is principally well suited for this purpose as each of those scripts illustrates the steps needed to integrate a certain component in a setup of low complexity. Because such scripts are executable, maintaining their consistency with the actual system is easy. If we provided a bunch of "howto" documents instead, we would have a hard time to ensure consistency. Inconsistent or misleading documentation, however, would be worse than having a no documentation.
Yes, i understand this. Yet, i didn't find get not setup that difficult either. Well, i think, 'you' are thinking of it to be 'very' perfect. It doesn't have to be, however if people get into trouble with the inconsistent documents they will surely come here to the ML.
Being frank, there is no issue without having such a document, as the audience of this framework wouldn't be that 'dump' to try it out and hack them. So, you don't have to focus on a complete newbie.
positive about it, taking our experience of the past weeks as some kind of empirical evidence. Your contributions are a good example. .-)
Yea, obviously, i do get lost in GIT at times. :D
I wasn't mocking you. :-) I just wanted to express that in contrast to our former Wiki, which was a deserted place, our GitHub repository actually receives love from outside of Genode Labs, for example in the form of your contributions.
Regarding your suggestion about a subfolder within 'doc/' for hosting user-maintained material, I am of course open for it.
Cheers Norman
-
Althaf -
Christian Helmuth -
Norman Feske