Page MenuHomePhabricator

Documentation Structure
Updated 650 Days AgoPublic

To manage to collate all the documentation and make a good user experience we need to plan carefully what structure we should use, what areas need to be added, and which parts of the site are no longer needed. This provides the structure proposed to organise T5827 and encompass all the changes in ticket T5826.

Migration

As we need to keep all of the old documentation online its important that no content is deleted - only moved if required.
Additionally most of this documentation will refer to the EFL interfaces release in EFL 1.21 and so we can't publish as we go.
Thankfully the proposal below allows for this - new documentation will not be created at existing URLs (with the exception of the main /docs page - which we will have to do last) old documentation will either be moved into /develop/legacy, have all links updated or will be left in place and have the valuable content adapted into the new docs.

We are also taking this opportunity to move to markdown documentation. All new files should be .md.txt instead of .txt (or, if adding from the web, pages should end with .md). Any pages which do not need to be changed in the restructure (not many) should be converted to markdown. Any .txt files in the repository will be interpreted as not yet ported to the new docs structure.

Structure

The following is a suggested layout with reference to the source / summary of each area:

docssourcecontentticket
/docsdokuwikiThe main documentation page focussed on user documentation or distribution etc
/docs/eNEWEnlightenment user documentationT5828
/docs/appsNEWNew documentation for our main apps (see About page for what they are)T6190
/docs/distrosdokuwikiInformation about which distributions ship E etc - currently in /distros
/docs/distros/<distro>dokuwikispecific info on each supported distro
devsourcecontentticketstatus
/developdokuwikiintroduction page to the documentation, summary of the areas documented, suggested reading for newcomersT6170 T6173
/develop/setupNEWQuick overview of ways to get a development environment set up - possibly to be found in an existing page somewhere
/develop/setup/<lang>NEWHow to get set up to use EFL with languages and envsT6578
/develop/eflNEWHigh level overview of the EFL project aims etc - possibly to be found in an existing page somewhere (?/docs/efl?)
/develop/toolsNEWDocumentation about the tools available (like user docs for devs :) )
/develop/tools/ediNEWEdi / IDE documentation (seems to belong here and not in /docs)T6166
/develop/apidokuwikiIntroduction to our APIs (much from /docs/efl) (C, Python etc)T5830 T6169 T5832 T6280setup
/develop/examplesNEWInformation about examples (to be created) that match the options in Edi to entice folk to get started with a new project (simple apps, games etc)T6167 T6165
/develop/examples/<lang>NEWExamples written for new interfaces
/develop/tutorialNEWtutorial - in sections per language as table belowT5835 T5840
/develop/tutorial/<lang>dokuwiki or NEWtutorial for our APIsstarted
/develop/guidesNEWprogramming guides - in sections per language as table below
/develop/guides/<lang>NEWprogramming reference guides for our APIsstarted
/develop/debugNEWdebugging guides - language-independent content
/develop/debug/<lang>NEWdebugging guides - language-specific contentstarted
/develop/legacydokuwikiLegacy docs intro (largely sourced from /docs/efl)T5829
/develop/legacy/api/dokuwikiSummary of the legacy API (from existing pages)
/develop/legacy/api/c/doxygenThe automatically generated API documentationT6126 T5833 T6168 T5838done
/develop/legacy/api/cpp/doxygenThe automatically generated API documentation (C++ root)done
/develop/legacy/tutorialdokuwikiMove the old C tutorial into this legacy location from /tutorialdone
/develop/legacy/program_guidedokuwikiMove the old C guides into this legacy location from /program_guidedone
contribsourcecontentticket
/contribdokuwikiAll the pages we have about developing for EFL - reporting, patching, debugging etc - *This would include moving style guides etc out of phab*T5831
/contrib/docs/NEWHow and what we document etcT6172
/contrib/devs/phabHow development works for those looking to contributeT5834

The following tables show the list of variants we are supporting - used to substitute <lang> above.

langstatusticketslegacy?
cin eoT6126 T5832 T5839 T5837both
cpp?both
luacore?
jsstartedyes
csharpnewT6131 T6127 T6128 T6130 T6129no
Last Author
ajwillia.ms
Last Edited
Jan 5 2018, 7:07 AM
Projects
None
Subscribers
pbrown66, ajwillia.ms, ghalfacree