[ell-i-developers] Re: Wiki pages: Runtime and Robot Framework Setup

  • From: Asif Sardar <engr.asif.sardar@xxxxxxxxxxxxxx>
  • To: ell-i-developers@xxxxxxxxxxxxx
  • Date: Mon, 9 Jun 2014 13:13:15 +0300

> Agree.  I can volunteer to fill in Mac OS X details, but given my limited
time it would be good if someone else would make a
> Mac OS X template page, pages on e.g. a Linux page, so that I could just
edit it and fill in the details.

I can make a template page and I will send you the link so that you can
fill all the details etc. But, I may send end of this week.

> I think the "user" documentation should be in the main wiki.  That is,
anyone who wants to use the Ell-i platform should find all
> the required information in the main wiki.  However, documentation for
the Ell-i developers, i.e. folks that work on enhancing
> some particular Ell-i component, such as the testing framework, the
Runtime, or the Eagle components, could well be in those
> Wikis.  In addition, each github repository could contain a pretty
similar wiki page linking to the main wiki for usage, and that
> particular wiki for internals.

> Why so?  Well, at least I find it hard to find information from a wiki
that is too large (and badly organised).  Hence, for the
> internals, I'd prefer smaller, topic specific wikis.  On the other hand,
I think that for people coming from outside it is easier to
> start with a single wiki giving information about the system as a whole.

>> - Unified wiki style/layout: pages should look the same, outlook-wise --
and they should look good. Likewise, wording on pages
>> should follow same basic guidelines. eg. which word classes are printed
in bold, which in cursive and which in monospace.

> I agree, completely.  And I think it is a good idea to cross-link all
terms specific to Ell-i, similar to how many Wikipedia articles
> cross-link to concepts that may not be that clear to all readers.

It will be very good if we could discuss it over few meetings at EIT
Otaniementie 19 B. Generally, we have meetings every Wednesday from
13:00-14:30. The meetings could also be arranged other days and/or times,
depending upon availability.




On Sat, Jun 7, 2014 at 10:21 AM, Pekka Nikander <pekka.nikander@xxxxxx>
wrote:

> >>>> I found this to be extremely important to write detailed wiki pages
> for the environment setup. If you have any suggestions to improve it, you
> are welcome!
> >>
> >> I would like to collaborate with you regarding the Ell-i documentation
> in general.
> >> [...]
> >
>
> > Depending on how much time and effort we're willing to put, there are
> many things to consider. ...
>
> I think all time spent on organising the documentation is very well spent.
>
> The testing framework is making good progress, with next requiring better
> integration with the emulator and then integration with the physical
> devices as systems under test.  That is probably best done more
> collaboratively, as it involves lots of unknowns, and there is no
> particular hurry with that.
>
> > Points to discuss (in no particular order):
> >
> > - Wiki pages must be easy to find. I'd vote for moving all content from
> other wikis to the main wiki and replacing content in project wikis with a
> simple link to main wiki. Alternative solution is to add lots of links to
> main wiki, but this is harder to maintain without any obvious benefits.
>
> I think the "user" documentation should be in the main wiki.  That is,
> anyone who wants to use the Ell-i platform should find all the required
> information in the main wiki.  However, documentation for the Ell-i
> developers, i.e. folks that work on enhancing some particular Ell-i
> component, such as the testing framework, the Runtime, or the Eagle
> components, could well be in those Wikis.  In addition, each github
> repository could contain a pretty similar wiki page linking to the main
> wiki for usage, and that particular wiki for internals.
>
> Why so?  Well, at least I find it hard to find information from a wiki
> that is too large (and badly organised).  Hence, for the internals, I'd
> prefer smaller, topic specific wikis.  On the other hand, I think that for
> people coming from outside it is easier to start with a single wiki giving
> information about the system as a whole.
>
> > - Unified wiki style/layout: pages should look the same, outlook-wise --
> and they should look good. Likewise, wording on pages should follow same
> basic guidelines. eg. which word classes are printed in bold, which in
> cursive and which in monospace.
>
> I agree, completely.  And I think it is a good idea to cross-link all
> terms specific to Ell-i, similar to how many Wikipedia articles cross-link
> to concepts that may not be that clear to all readers.
>
> > - Split project/target-specific information into their own pages and
> consolidate environment setup into more generic instructions. Here we also
> need to decide which OSes we want to support; I strongly believe whatever
> is supported is well-tested: the STM32F4 instructions[1] I wrote were
> tested on a barebones Ubuntu install made with debootstrap, in order to
> confirm the package lists and build instructions.
>
> Agree.  I can volunteer to fill in Mac OS X details, but given my limited
> time it would be good if someone else would make a Mac OS X template page,
> pages on e.g. a Linux page, so that I could just edit it and fill in the
> details.
>
> > - Concentrating on providing information that cannot otherwise be easily
> found
>
> Yes.  It is also good to have a brief Ell-i specific summary of
> information that is essential but can be found from elsewhere, with then
> links to the more general stuff elsewhere.
>
> > The wiki should instead have lots of links.
>
> I concur.  Try to keep the contents to the essential and somewhat
> specific, link to more generic stuff on other pages or elsewhere.
>
> > Based on discussion, we then make a TODO-list with concrete action
> points and follow through. eg.
> >
> > * Consolidate host toolchain setup instructions into separate page
> > ** A landing page with brief overview/explanation of software included
> > in the toolchain and links to OS-specific setup pages with bare-bones
> > setup instructions. Additionally, link to external pages with content we
> > don't intend to provide (eg. Eclipse or other GUI IDE setup).
>
> It would be good to have a mostly-similar landing Wiki page in each of our
> repositories, pointing to the main Wiki and then, if there are
> repo-specific pages of the internals, separately to those.
>
> > ** OS-specific page: Ubuntu 12.04
> > ** OS-specific page: OSX 10.?
>
> I think we need pages for OS X 10.8 (Mountain Lion), 10.9 (Maverics), and
> 10.10 (Yosemite).
>
> > p.s. Pekka, I ran into Camillo today. He says "hi" :)
>
> Tnx!
>
> --Pekka
>
>


-- 



*With Best Regards,Asif Sardar.+358 43 8265795*

Other related posts: