Page MenuHomePhabricator

Improve overall EFL documentation
Open, HighPublic

Description

Enlightenment documentation need a general overhaul to be easier for all our users to find the documentation they are looking for. We can start by having 3 broads type of users :

  • Applications users (Enlightenment, Terminology, ...)
  • Third party developers (Using EFL from C, C++, C#, Python, JS, ...)
  • EFL contributors

Each of them are looking for different kind of information and so should get a different introduction. Our references API documentation should also be improved to take into account our new Eo based API and the legacy one. We should also provide a new set of guide, tutorials and examples to cover the new EFL API.

Related Objects

StatusAssignedTask
OpenNone
Resolvedajwillia.ms
Resolvedghalfacree
Resolvedajwillia.ms
OpenNone
Resolvedghalfacree
Resolvedghalfacree
Resolvedajwillia.ms
Resolvedajwillia.ms
OpenNone
OpenNone
OpenNone
DuplicateNone
DuplicateNone
Resolvedsegfaultxavi
Resolvedsegfaultxavi
Resolvedajwillia.ms
Resolvedsegfaultxavi
DuplicateNone
Resolvedajwillia.ms
Duplicateajwillia.ms
Resolvedajwillia.ms
Resolvedajwillia.ms
Resolvedajwillia.ms
OpenNone
Opensegfaultxavi
Opensegfaultxavi
Resolvedlauromoura
Opensegfaultxavi
Resolvedsegfaultxavi
Opensegfaultxavi
Resolvedsegfaultxavi
Resolvedsegfaultxavi
Opensegfaultxavi
Resolvedajwillia.ms
Resolvedajwillia.ms
Resolvedajwillia.ms
InvalidNone
Resolvedajwillia.ms
OpenNone
Openzmike
Resolvedajwillia.ms
Resolvedajwillia.ms
Resolvedajwillia.ms
Resolvedbryceharrington
Resolvedajwillia.ms
Resolvedajwillia.ms
Resolvedajwillia.ms
Resolvednetstar
Resolvedajwillia.ms
Resolvedpbrown66
Resolvedghalfacree
Resolvedajwillia.ms
Resolvedghalfacree
Wontfixghalfacree
Resolvedajwillia.ms
Resolvedajwillia.ms
Opensegfaultxavi
Resolvedajwillia.ms
Resolvedajwillia.ms
Openajwillia.ms
Openq66
Opensegfaultxavi
cedric created this task.Aug 3 2017, 11:32 AM
cedric added subscribers: ajwillia.ms, myoungwoon.

For better support with external tools, all code related documentation should be moved to markdown format.

cedric added a comment.Aug 3 2017, 2:48 PM

You may want to read our documentation on writing documentation :-) https://phab.enlightenment.org/w/doc_system/ . Additionnally this concern only https://git.enlightenment.org/core/efl.git/ for the reference API.

cedric added a comment.Aug 3 2017, 4:04 PM

A topic that is not exactly to be much covered this time is writing edje files. This would be for another time.

zmike added a project: efl.Aug 22 2017, 3:43 PM
rbtylee added a subscriber: rbtylee.Sep 7 2017, 2:30 AM
cedric raised the priority of this task from Wishlist to High.Oct 2 2017, 3:17 PM

As someone that just got into EFL recently myself, Cedric asked me for some getting started recommendations for new tech writers as they onboard.

There are a lot of acronyms and jargon and toolage that is EFL-specific that won't make sense to you at first. (A lot of it still doesn't, for me...) The https://phab.enlightenment.org/w/doc_system/ might be a bit confusing because of all the jargon, and so might not be the best spot to jump in initially.

Actually, I would recommend new tech writers start by checking out the EFL from git, and getting it to build. The process is documented well enough, and it requires little EFL internals knowledge so is a nice accomplishment you can do on day #1. Plus you'll need it later.

Next, https://www.enlightenment.org/docs/efl/start has a table with a concise listing of what the various pieces are, and defines some jargon. Handy reference.

There isn't really a good high-level explanation of EFL, but the closest I've found is actually on the Tizen website, at https://developer.tizen.org/development/guides/native-application/user-interface/efl. That webpage provides depth and context that you may find handy when writing EFL docs. Might even be some cut-and-pasteable chunks from there, but use your judgment. Bookmark this and revisit often.

At this point you can probably digest https://phab.enlightenment.org/w/doc_system/ effectively. I haven't actually used this myself, so have no tips.

One question I have, I don't know if all the tasks on this ticket are doable via docuwiki alone. EFL uses Phabricator to host and manage its git trees, which is what I've been using. Instead of git push you do arc diff. If you will need to use phabricator, then some time installing/learning it is worth doing as part of the onboarding. Along with that, learn how to generate the static docs locally -- the code docs posted at https://www.enlightenment.org/docs are generated from the EFL releases, not from EFL's git trunk, so for tech writing purposes they'll be out of date. I don't have the commands at hand for generating the docs but once you've built the EFL codebase it's straightforward to do.

The Eo docs that you've seen discussed here and there is a new format for writing API documentation. You can think of it as like the doxygen comments extracted from the code files and put into .eo files. Actually, they're used for generating API code in various programming languages so there's a bit more to them than that. I imagine there must be a place that defines the syntax of .eo files but I've not run across it yet; it would be worthwhile to either find it or if it doesn't exist yet, write it.

As I've gone through the documentation myself, there are some specific documentation problems I've noticed that are very common:

  1. A lot of code docs are too terse. E.g. the docs for 'set_foo(bar)' might say, "Sets foo, given bar", without saying what foo is, or why you'd want to set it to bar, or what the effects are. A modest amount of code delving can usually elucidate these and help you make the docs actually informative. While it's true that most of EFL's API has code documentation, a bulk of it is of this variety and won't be actually informative to anyone, and should be further elaborated.
  1. Grammar issues. Quite a bit of documentation was written by non-native English speakers, so word choice, spelling, punctuation, etc. issues are pretty common. These are easy low hanging fruit, although sometimes I've found just fixing the issues isn't enough to clarify the docs, and they really could benefit from a more extensive revision. Code gets copied around, and so the mistakes get copied too, so when fixing something, perform a search on the larger codebase to spot other places to fix.
  1. Consistency. Docs have been written by many people, so it's understandable that everyone has their own style, but it leaves the docs rather uneven for the reader. There should exist a documentation equivalent of a code style guide, with guidelines like, "Lead with a verb in @brief's," "Omit periods from parameter definitions", etc.
  1. High level explanation. Carsten once told me the best thing to do is ask, 'Why?' It's great advice. Unfortunately the EFL documentation leaves a *lot* of obvious why's unanswered. In particular, 'Why does this component/function/thingee exist?' is infrequently addressed. Several of the tasks are asking for 'Intro to...' - great places to give good answers to this question.
  1. Why doesn't this work?? I like to imagine that my reader is someone who didn't read any docs to begin with, and just dove in cargo culting their app, and now their stuff is acting weird and they don't know why, and have come to my docs as a last resort. So I try to answer questions I think they'd have: What are the failure modes for this routine, why can it fail? What side-effects might it have? What assumptions might catch you? Where is a working example that shows proper usage of the routine?

Some workflow steps, apart from the actual coding of the project, which might be worth considering providing docs for at some point.

  1. Hosting (e.g. gitlab/github or whatever). Short paint-by-numbers tutorial for setting up git, bug tracking, etc. at popular hosting platforms. Pointers to hosting platform docs for more info.
  2. Setting up CI for an EFL-based project. What unique provisions/requirements does EFL have for CI? Pointers to hosting platform docs for more info.
  3. Debugging tips and techniques. Logging best practices, crash dump analysis tips, memory leak detection, common problems, useful static tests, etc.
  4. Performance optimization of EFL apps. How to measure performance, guidelines on identifying and resolving bottlenecks, common problems, etc.
  5. Deploying EFL apps to Tizen. Getting registered, uploading your app, announcing, releasing new versions
  6. Deploying EFL apps to other platforms. Focus on EFL-specific deployment issues, point to appstore/distro/os-vendor docs for more info.
In T5826#93592, @cedric wrote:

For better support with external tools, all code related documentation should be moved to markdown format.

I added T6170 to track the tasks needed to make that happen

Some workflow steps, apart from the actual coding of the project, which might be worth considering providing docs for at some point.

  1. Hosting (e.g. gitlab/github or whatever). Short paint-by-numbers tutorial for setting up git, bug tracking, etc. at popular hosting platforms. Pointers to hosting platform docs for more info.

This first point seems like it might be a bit generic - if we were using github it would be more meaningful :)

Items 3 and 4 are essential and may already be on our list.
Should 5 be on the Tizen docs rather than EFL? We could certainly point to them from a high level overview in our docs?

If Tizen has docs that are felt to be suitable, then yes definitely. However, my guess is their docs are bitrotting and will be difficult to get updated, so would suggest having something maintained as part of EFL's docs (even if it just copies or cross references the Tizen docs in many places). Not having gone through creation & deployment of a Tizen app myself, I couldn't vouch for the quality of their docs, but they felt a bit lightweight to me.

bu5hm4n added a project: Restricted Project.Jun 11 2018, 2:58 AM
zmike edited projects, added Restricted Project; removed efl.Jun 11 2018, 6:54 AM
bu5hm4n edited projects, added efl: docs; removed Restricted Project.Jun 11 2018, 7:42 AM
zmike added a subscriber: zmike.

A #Goal ticket should not be set to a milestone.