Documentation Structure
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:
docs | source | content | ticket |
---|---|---|---|
/docs | dokuwiki | The main documentation page focussed on user documentation or distribution etc | |
/docs/e | NEW | Enlightenment user documentation | T5828 |
/docs/apps | NEW | New documentation for our main apps (see About page for what they are) | T6190 |
/docs/distros | dokuwiki | Information about which distributions ship E etc - currently in /distros | |
/docs/distros/<distro> | dokuwiki | specific info on each supported distro | |
dev | source | content | ticket | status |
---|---|---|---|---|
/develop | dokuwiki | introduction page to the documentation, summary of the areas documented, suggested reading for newcomers | T6170 T6173 | |
/develop/setup | NEW | Quick overview of ways to get a development environment set up - possibly to be found in an existing page somewhere | ||
/develop/setup/<lang> | NEW | How to get set up to use EFL with languages and envs | T6578 | |
/develop/efl | NEW | High level overview of the EFL project aims etc - possibly to be found in an existing page somewhere (?/docs/efl?) | ||
/develop/tools | NEW | Documentation about the tools available (like user docs for devs :) ) | ||
/develop/tools/edi | NEW | Edi / IDE documentation (seems to belong here and not in /docs) | T6166 | |
/develop/api | dokuwiki | Introduction to our APIs (much from /docs/efl) (C, Python etc) | T5830 T6169 T5832 T6280 | setup |
/develop/examples | NEW | Information 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> | NEW | Examples written for new interfaces | ||
/develop/tutorial | NEW | tutorial - in sections per language as table below | T5835 T5840 | |
/develop/tutorial/<lang> | dokuwiki or NEW | tutorial for our APIs | started | |
/develop/guides | NEW | programming guides - in sections per language as table below | ||
/develop/guides/<lang> | NEW | programming reference guides for our APIs | started | |
/develop/debug | NEW | debugging guides - language-independent content | ||
/develop/debug/<lang> | NEW | debugging guides - language-specific content | started | |
/develop/legacy | dokuwiki | Legacy docs intro (largely sourced from /docs/efl) | T5829 | |
/develop/legacy/api/ | dokuwiki | Summary of the legacy API (from existing pages) | ||
/develop/legacy/api/c/ | doxygen | The automatically generated API documentation | T6126 T5833 T6168 T5838 | done |
/develop/legacy/api/cpp/ | doxygen | The automatically generated API documentation (C++ root) | done | |
/develop/legacy/tutorial | dokuwiki | Move the old C tutorial into this legacy location from /tutorial | done | |
/develop/legacy/program_guide | dokuwiki | Move the old C guides into this legacy location from /program_guide | done | |
contrib | source | content | ticket |
---|---|---|---|
/contrib | dokuwiki | All 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/ | NEW | How and what we document etc | T6172 |
/contrib/devs/ | phab | How development works for those looking to contribute | T5834 |
The following tables show the list of variants we are supporting - used to substitute <lang> above.
- Last Author
- ajwillia.ms
- Last Edited
- Jan 5 2018, 7:07 AM
- Projects
- None
- Subscribers
- pbrown66, ajwillia.ms, ghalfacree