Loading...
 
Skip to main content

Documentation

Forum List Topic List

Forums » Documentation » Documentation challenges
 
Thread actions
Print this page
  • Print all pages

    • Documentation challenges

    Posted by Bryan Pfaffenberger posts: 10 United States


    Two pages to look at (for discussion): FeatureX and DocConventions.

    Here's my quick take on the challenges we face:

    (1) The documentation is not discoverable from the tw.o menu. We need a custom menu for the documentation.

    (2) Marc developed a rather complex (and I think somewhat inflexible) plan for differentiating among the various types of documentation pages (FeatureXGloss, FeatureX, FeatureXDoc, etc.). We need to decide whether we should consistently follow this or make changes. Taking a cue from Apache, MySQL, and PHP docs (and others), I prefer a more flexible approach with the following sections:

    installation
    getting started tutorials (admins)
    getting started tutorials (users)
    reference (users)
    reference (admins)
    reference (devels)
    how-to (i.e., for setting up a new site with the features you want)

    The part that Marc's nomenclature described is the reference manual (user and admin version).

    (3) The various contributions need to be collated into (I think) html pages (zipped) and pdf. Perhaps the developers could write some code to output these from Wiki structures - they've talked about it, I think.

    My big concern is that people are going to start writing stuff using a page nomenclature that will later require a huge reorganization.

    Reads: 2718
    Posted by Philippe Cloutier posts: 1001 Canada

    Quick answer

    1. I like the idea of a tutorial module
    Let's brainstorm some content :
    Tutorial
    About Tiki
    What's a Wiki
    Help about this feature
    add your ideas
    This had the advantage of being extremely simply removable from the interface.

    2. I don't think Marc's way is inflexible.
    Actually, we already have the InstallGettingStarted for admins (should probably be renamed GettingStartedAdmin)
    I don't think we have a GettingStartedUser (Doc-nothing?) yet, please correct me. This will be a must, but it doesn't need a change of marc's nomenclature IMHO.
    Also we have a GettingStartedDeveloper as HowToDev.

    I just changed our HowTo page to Archive(HowTo) because it was outdated. See there if you get an idea, though I'm not sure what you mean by HowTo.

    3.Yes...

    I'm waiting other people's replies😊



    Posted by Philippe Cloutier posts: 1001 Canada

    Hi PocketAces,
    this is just a tip about how to contribute to the project.
    Since there are too many things to change in Doc, it's useless to throw small ideas like these for approbation. If you red DocConventions and etc. pages, and think a change should be made, you should do it, and in case of doubt, you can always give us a notice here (or in the edited page itself) about why you made the change.
    Otherwise there would be too much requests like these to treat.

    Cordially