[#313] - Initial restructure of docs for better organization
- Closed
- 8 Mar 2014
- Medium
- Build: master
- # 313
- Diff
- joomla:doc-structure
- Success default The Travis CI build passed Details
User tests: Successful: Unsuccessful:
To help better organize the documentation, especially as more is added (and it should be), I'm suggesting we restructure the Documentation folder in the filesystem to group docs into top level categories.
This will require some rewrites to the make docu CLI command to support, but that's easy enough I'd say. Also up for discussion would be the URL routing here. Instead of http://issues.joomla.org/devdox/dox-app-debug, perhaps a URL like http://issues.joomla.org/docs/applications/debug (which matches the file structure still) could be used.
Also, I started a little bit on standardizing English use. Our default language is en-GB, might as well get the docs right with that too.
It's definitely a work in progress if we go through and do everything.
Personally, I think it is worth it to get a clean and organized structure.
Translating the docs isn't something I've thought about at all, but that's
a unique challenge too.
On Wednesday, March 5, 2014, Nikolai Plath notifications@github.com wrote:
Well, our current solution is indeed meant only for "very small
documentation projects" that contain only a "hand full of" pages. Let's say
about one or two dozens ;)At the moment you try to "structure" things you will face some additional
challenges (let alone multilanguage).One thing we already have implemented is the online browsing of the
markdown files rendered as a simple. This would need some (JS)
tree thingy.Our current router would require us to create a new category element like
http://issues.joomla.org/docs/:category/:alias
Or shall we go with
http://issues.joomla.org/docs/:section/:category/:alias ?
Welcome to Joomla! 1.0 :)
We could also use the "Wiki style" and just add a ?page=path/to/pageparameter...Another functionality we have currently in place is the "Text App" that
currently also displays the compiled markdown files with their strange doxprefixes. This would also need some work (if we still want it to work).So right now some of the documentation would be "inaccessible" if we merge
this.Reply to this email directly or view it on GitHub#313 (comment)
.
Feel a tough work here. Should we focus on it now? There is an activty around JTracker recently and for me it's better to focus on UI currently.
| Status | New | ⇒ | Closed |
| Closed_Date | 0000-00-00 00:00:00 | ⇒ | 2014-03-08 20:28:23 |
Should we focus on it now?
While I was asking me the same question, I think it's a good idea ;)
Well, our current solution is indeed meant only for "very small documentation projects" that contain only a "hand full of" pages. Let's say about one or two dozens ;)
At the moment you try to "structure" things you will face some additional challenges (let alone multilanguage).
One thing we already have implemented is the online browsing of the markdown files rendered as a simple
<ul>. This would need some (JS) tree thingy.Our current router would require us to create a new
categoryelement likehttp://issues.joomla.org/docs/:category/:aliasOr shall we go with
http://issues.joomla.org/docs/:section/:category/:alias?Welcome to Joomla! 1.0 :)
We could also use the "Wiki style" and just add a
?page=path/to/pageparameter...Another functionality we have currently in place is the "Text App" that currently also displays the compiled markdown files with their strange
doxprefixes. This would also need some work (if we still want it to work).So right now some of the documentation would be "inaccessible" if we merge this. But I would definitely agree that expanding our documentation and organizing it into categories (folders) would be an excellent idea :)