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

  • From: Pekka Nikander <pekka.nikander@xxxxxx>
  • To: ell-i-developers@xxxxxxxxxxxxx
  • Date: Sat, 7 Jun 2014 10:21:19 +0300

>>>> 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 

> p.s. Pekka, I ran into Camillo today. He says "hi" :)



Attachment: smime.p7s
Description: S/MIME cryptographic signature

Other related posts: