Loading...
 
Skip to main content

Documentation

Forum List Topic List

 
Thread actions
Print this page
  • Print all pages

    • Documentation: structure

    Posted by klang posts: 30

    There is a lot of good documentation on tikiwiki, certainly compared to other cms systems I've looked at - but the structure looks an absolute mess to me, as a newcomer. And that is important, because newcomers need the docs more than anyone.

    Take the homepage:

    http://doc.tikiwiki.org/tiki-index.php?page=HomePageQuestion

    There are (at least) 3 different menus offering documentation. Which is the right one to use? Is it the one called 'Documentation', or the prominent menu bar at the top, or the list of main content headed 'Learn'?

    As a newcomer wanting to contribute to the docs, I can't start hacking at the front page. But it seems to me that is the most important part of the documentation that needs fixing.

    Am I wrong?😕

    My proposal would be to have a single menu - probably repeated on the page - with a strong tree structure so that you don't go down one branch and return on another as at present. If the Documentation menu is to be the main menu, it needs to start with an introduction item; features should list the features, not explain them in detail (or should be called something else), and so on.

    btw what does 'refactor' mean? It isn't in the dictionary I just checked.... 😉

    Reads: 3196
    Posted by Gary Cunningham-Lee posts: 4675 Japan

    Thanks for the feedback; it's always good to get opinions from people who are looking at things fresh. The documentation is a work in progress that has two basic challenges. One is to keep up with the new features and other changes in Tikiwiki; the other is to try to improve the organization (including navigation) of the documentation pages themselves.

    Well, the docs are a wiki, and anyone who is interesting is invited to help out; unfortunately the people who tend to help most are already busy with other aspects of the project that have priority.

    I guess refactor is too new or too much a niche term to be in dictionaries, but it gets about three million hits on Google so isn't exactly obscure. WikipediaQuestion says "Code refactoring is the process of changing a computer program's code to make it amenable to change, improve its readability, or simplify its structure, while preserving its existing functionality." Editorial comments like "this page needs refactoring" shouldn't be part of the visible page content for normal users, so this is an aspect of the docs that needs refactoring. 😉

    -- Gary themes.tw.oQuestion


         Posted by klang posts: 30

    Hi Gary - yes I'm trying to help out - trying to decide what to tackle. My question 'which of the 3 menus' is a serious one - which one should a user try first? Once I know that I'll follow it and start editing.

    My 'refactor' comment was a bit 'tongue in cheek' of course - I know it means eg 'changing the factors of 12 from 2 * 6 to 3 * 4' 😉

    One thing I can fix is on Welcome Authors:
    http://doc.tikiwiki.org/tiki-index.php?page=Welcome+Authors&bl=yQuestion

    "If in doubt, ask in the Author Coffeeshop forum."

    The Author Coffeeshop forum does not seem to exist - is that right? Should discussion be directed here? Or is there somewhere else that discusses docs?

    Posted by Xavier de Pedro posts: 1817 Catalan Countries

    Dear klang:

    Thanks for your comments. the right place to post them is at the Editorial Board Meeting underway:
    http://doc.tikiwiki.org/tiki-index.php?page=Editorial+Board+Meeting+2008+08Question

    In addition, you can already fix wrong things on homepage (I've added you to the ))DocContributorsgroup, which has some special extra perms, according to what we decided in a previous meeting - ((doc:ebm. you are already in Doc.

    For other more important changes, you'd better post them in the ebm underway, and let other people taking care of doc.tw.o discuss about it, and decide about it with the highest possible consensus.

    There is plenty of room for you (and many others) to suggest or perform improvements on doc.tw.o, so that you are very welcome! 😊

    Cheers

    Xavi

    P.S. My own opinion about the 3 menus thing is to keep/improve the one on the left column, and where needed, the one in Documentation (which is an structure, and so far, plain registered users can't edit for security reasons). The hand made ones in other pages, go ahead to fix or edit them once you know how to improve them. And the "new user"-point of view is very important!!!!


         Posted by klang posts: 30
    OK, thank you - I've made a few concrete suggestions on the EBM page. Do tell me if I'm getting it wrong (writing in the wrong places etc) - that's certainly possible 😉. And I've made a few minor edits on pages, mainly to improve clarity.
    Posted by Xavier de Pedro posts: 1817 Catalan Countries

    thanks, klang. everything is fine!

    And about the reference to "Author coffeshop forum", since the link to that forum is wrong (forum is not being used any more), you could fix taht yourself! (a-la-wiki way), without proposing a motion to the current ebm


         Posted by klang posts: 30

    >you could fix taht yourself!

    Well, I would do - but the page is locked...

    Posted by Xavier de Pedro posts: 1817 Catalan Countries

    You are right. I unlocked the page, and I edited a couple of things myself.
    Feel free to improve.