Page MenuHomePhabricator

Reorganize Enlightenment documentation website
Closed, ResolvedPublic

Description

Enlightenment documentation needs to have a better entry point for each class of potential user of it. The first page should be clearly splitted for :

  • Application users
  • Third party developers
  • EFL contributor

And likely direct to a specific page for each of this category. The third party developers should also allow for them to find documentation that match there own preferred language, not just C. We have a large community of Python developers using EFL (if not the majority of third party developers), but with the work on Eo and EFL interfaces we should have a lot of other language well supported (C++, C# and JS do have a generator in EFL tree). Finally the hierarchy of the docs directory should actually reflect this and allow an easier grab of a sub tree for the documentation concerning a specific language.

Proposed structure in https://phab.enlightenment.org/w/doc_system/doc_structure .

cedric added a comment.Aug 3 2017, 3:01 PM

Oh, I forgot, we do not want to loose our documentation about our legacy API or EFL 1.0. So we should have a way for third party developers to figure out which one they want and go the right way. Maybe we will want to keep legacy the first entry until the end of the year once we officially push forward with the first release of EFL interface work.

cedric raised the priority of this task from Wishlist to High.Oct 2 2017, 3:17 PM
Herald assigned this task to zmike. · View Herald Transcript
Herald raised the priority of this task from High to Incoming Queue. · View Herald Transcript
cedric removed zmike as the assignee of this task.Oct 2 2017, 3:27 PM
cedric added a subscriber: zmike.
zmike triaged this task as TODO priority.Oct 6 2017, 9:02 AM

I think we are talking about https://www.enlightenment.org/docs, yes? I agree that the current page is very busy, probably too much so. Here are my suggestions to make it much simpler while still routing visitors to where they want to go in a non-confusing way. Note this is an early idea and draft:

First include a non-technical definition of Enlightenment for all users (not only developers) framed from the point of view of how a user would first interact with Enlightenment:

Enlightenment is the space where you interact with your apps on many Samsung devices. The screen on your Samsung fridge, camera, or watch shows you Enlightenment. You can also run Enlightenment on a Linux-powered desktop computer."

Maybe include some screenshots from several devices to illustrate what we mean with the above.

Then have three distinct areas:

End users

To learn more about how to use Enlightenment and become an enlightened power-user
[CLICK HERE] <-- Button?

Developers

To learn how to build your own apps and run them on devices that use Enlightenment
[CLICK HERE]

Enlightenment is free open source software supported by a friendly and welcoming community. Do you want to join us and help us make it better?
[CLICK HERE]

What exists is currently all within /docs - linked from "Docs" in the header bar. There is a "Devel" link that takes folk straight to phab.
I think we could change "Docs" to link to user documentation (still in /docs) then "Devel" (or similar) could link to developer documentation (in /develop) with a new "Contribute" button linking to /contrib which would include docs and a link to phab as before.

As per your example above perhaps the bottom of our main documentation page could have the developer / contributor summary/buttons etc in case folk head straight to the user documentation?

ajwillia.ms updated the task description. (Show Details)Oct 12 2017, 1:40 AM

So you are proposing two prongs instead of three:

  • One link for end users to documentation on how to use the environment and apps
  • The other link for developers, which in turn will lead visitors either to the section for app developers or to contributors to the Enlightenment project.

Sounds fine to me.

As per your example above perhaps the bottom of our main documentation page could have the developer / contributor summary/buttons etc in case folk head straight to the user documentation?

Yes, that's a good idea. I think it will not create confusion in any way.

ajwillia.ms closed this task as Resolved.Dec 1 2017, 2:23 AM

This is all done except changing the "Develop" link at the top of the page.
Closing now as that minor change is going to happen at the last minute...