[ell-i-developers] Re: Wiki pages: Runtime and Robot Framework Setup
- From: "Atte Peltomaki" <atte.peltomaki@xxxxxx>
- To: Asif Sardar <engr.asif.sardar@xxxxxxxxxxxxxx>
- Date: Mon, 9 Jun 2014 14:01:29 +0300
On Mon, Jun 09, 2014 at 01:13:15PM +0300, Asif Sardar wrote:
> > 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'd prefer to avoid making template pages. These have a nasty habit of
never getting populated, and having no page is better than having an
"under construction" page.
> > > ** 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).
I happen to be getting a MacBook laptop from work soon-ish, which is a
great chance for testing and documenting the basic environment setup.
But, I doubt we'll be able to reasonably maintain documentation for more
than a single OSX version. If we cannot guarantee correctness of the
instructions, it's better not to provide them at all and let users adapt
docs for a different version.
> > 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.
Markdown syntax and GitHub wiki are not intended for handling large
amounts of information. I'd also venture that the "wiki" value of a
GitHub wiki is quite low, not least because nobody can edit the pages
without being granted permission to. But also because wikis in general
tend to suck for anything beyond a public scratchpad.
If we need to start organizing a non-trivial amount of data, a natural
step would be migrating to another documentation system, eg. asciidoc
or a more fully-featured wiki.
> > > - 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.
During work hours is a bit inconvenient, I do have a job to do. Can you
join #ELL-i on Freenode IRC for arranging a suitable time? And since I'm
not getting paid for this, I'd prefer meeting in a pub ;)
--
Atte Peltomäki
atte.peltomaki@xxxxxx <> http://kameli.org
"Your effort to remain what you are is what limits you"
Other related posts:
