[ell-i-developers] Re: Wiki pages: Runtime and Robot Framework Setup
- From: "Atte Peltomaki" <atte.peltomaki@xxxxxx>
- To: ell-i-developers@xxxxxxxxxxxxx
- Date: Fri, 6 Jun 2014 16:38:09 +0300
On Wed, Jun 04, 2014 at 02:40:33PM +0300, Asif Sardar wrote:
> On Wed, Jun 4, 2014 at 2:32 AM, Atte Peltomaki wrote:
> > On Tue, Jun 03, 2014 at 07:24:22PM +0300, Asif Sardar 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!
> > >
> > > Please check the following wiki pages:
> > >
> > > Ell-i Runtime
> > >
> > https://github.com/Ell-i/Runtime/wiki/Compiling-and-development-environment-setup
> > >
> > > Ell-i Robot Framework
> > > https://github.com/Ell-i/ELL-i-PyBot-Tests/wiki/Read-Me
> >
> > Sweet! I was about to write the same environment setup page, but got
> > hung up hacking :] At a glance the pages look great, I'll try to go
> > through them in detail by end of week.
>
> I would like to collaborate with you regarding the Ell-i documentation in
> general.
>
> I will wait for your comments and then modify the above links more e.g.
> move repeated code and explanation to other page.
Okay, I've read through the docs with a bit more thought. The pages are
a very nice improvement, good work!
Depending on how much time and effort we're willing to put, there are
many things to consider. First, if we're going to to put any non-trivial
amount of effort into this, we should off start by meeting and
discussing this over a few beers. Or if that's difficult to arrange,
I'll elaborate my thoughts over email.
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.
- 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.
- 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.
- Concentrating on providing information that cannot otherwise be easily
found, eg. I'm pretty sure it would've been easier to link to one of the
gazillion git tutorials rather than writing another one. Following
this thought, the wiki should instead have lots of links. This is also
why I kept the STM32F4 page very short and absent of explanations: if
one doesn't know what GCC, GDB or toolchain mean, Google does know and
is willing to share. Trying to explain all this on a single page would
be an impossible task anyway, so it's better not to even try.
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).
** OS-specific page: Ubuntu 12.04
** OS-specific page: OSX 10.?
And so forth.
[1] https://github.com/Ell-i/Wiki/wiki/STM32F4-setup
p.s. Pekka, I ran into Camillo today. He says "hi" :)
--
Atte Peltomäki
atte.peltomaki@xxxxxx <> http://kameli.org
"Your effort to remain what you are is what limits you"
Other related posts:
