43 replies to this topic

[Randy]

I think Etomite is a perfect tool for the documentation. It has everything needed (plus).

To be overtly (and overly) consistent, it seems the documentation is fractured. A great deal of the content that should be in the documentation is in the forum posts instead. I know when I try my best to search for an answer in the forum I struggle. I know when I try my best to answer someone's question am inadvertently documenting Etomite functionality. The obscure forum post, that even I may never find again, might be valuable if it were consolidated with other related information in the right place.

What makes the forum exactly wrong for documentation is the lack of context. I don't recommend the forums change in any way. What I'm suggesting is documentation is different than discussion, but documentation comes from discussion.

I would rather answer the question in the 'documentor' rather than in a post. If I go to the documentation source and find the answer, I would simply redirect the person to the answer via the forum. If this is a truly unique question (because there is no answer in the documentation), then I answer the question via the 'documentor' and then redirect them to the documentation via the forum. Eventually most questions are answered with redirects to the docs vs. answers in forum posts.

If you punch up [Documentation][Users & Permissions][Working with Permissions] one can completely understand the context of the information being displayed.

If you do a search in the forums on the term 'permissions' you get 17 pages of post titles back. Searching on 'user permissions' returns 25 pages of them. In these very long (daunting) laundry lists of posts, there is nothing to indicate where an answer lies with them. The primary reason is there is no context to glue all the thoughts into congruent answers.
=======
Recommend:

Publish a style guide for documentation and enforce it.
Those with rights* update the documentation pages via Etomite text entry capability using the style guide.
The pages would be updated with answers that are posted in the forums.
The author would then direct the question asker to the doc page with the answer.

====
*"Those with Rights" = limited number of community members with an account, agree to strict guidelines about content, agree to the use of their real name, agree unconditionally to produce answers to forum questions in the documentation first (or be subject to revocation of edit privileges), etc.
====

Forget TRAC then. All this can be done in Etomite. Then you don't have to worry yourselves over us unreliable volunteers. Albeit one of us is desperately trying find ways to ease your burden with some of this stuff. But hey....whatever.

[Dean]

Organise a team, and we can get started then :-)

[Randy]

Done. You already did it. I can be found here: http://www.etomite.com/staff.html

You miss the point Dean. It's the disciplined approach...not the collection of souls.

This requires two things:

1) Establish some basic guidelines like the ones I suggested and ask the current 'team' you already have to follow through on the promise of updating the documentation (when appropriate) with answers instead of taking the easy way out and answering questions in the forum.

2) Enforcement.

I can do neither of those things as I'm not part of the 'team', and am not in a position to be able to enforce anything without the authority to do so.

[Dean]

Ah! That list is out of date... time to clean up me thinks

[Randy]

Here is a case in point:
Mike is always very helpful to folks and I know they appreciate the help. He has done nothing wrong and don't want this post to insinuate that...

This post: http://www.etomite.c...h...ost&p=42260 offers guidance on the use of Etomite specific tags and compares them to PHP specific string oriented troubles. It's a good post and I'm sure will be found useful.

Here's the point. I looked through the docs and could not find a discussion of the Etomite [~*~] syntax. It would have been really really cool for Mike to add the very same comments on a documentation page and then redirect the asking user to the docs he just wrote. Now there is a permanent guide to the answer that everyone benefits from.

If the answer was not perfectly precise, it would be easy enough to fix it up. It would still be in a single place and not clearified over several posts.

Hope this helps clarify my earlier comments.

Mike -- would you mind doing this?

[mikef]

Mike -- would you mind doing this?

I was part of the documentation team, but was removed.
If anyone else in the documentation team wishes to copy those comments into the documentation they are welcome to do so.

[Ralph]

I wasn't aware that the tags were no longer mentioned in the documentation...

[Randy]

Point on Ralph. Just because I didn't see it (it=[~*~] tag) doesn't mean it wasn't there. But if the focus was on answering questions centrally and consistently, then we'd all be more aware of what's there.

So let's not lose the point: Answers to common questions should come from the documentation not the forum. Those with answers should have a way to place those answers in the central documentation, and then be continuously encouraged to do so there rather than the forums.

Currently, neither of these things are happening and it's my opinion this is hurting the effectiveness of aid provided to the community (and causes you and Dean more work).

[Jelmer]

I agree with Randy. I'd rather provide a solution directly into the docs than into the forums. If we could agree on a decent FAQ system I think we could manage, couldn't we?

[Randy]

I agree with Randy. I'd rather provide a solution directly into the docs than into the forums. If we could agree on a decent FAQ system I think we could manage, couldn't we?

FAQs are good tools and necessary. Unfortunately, I just don't think they are a replacement for documentation. My reasoning is that FAQs, like forum posts, don't have as strong a context built around them as is provided by a chapter, topic, page, and paragraph.

Documentation is strong for that reason.

[Randy]

ok...here's an example. http://trac.seagullproject.org/wiki

The contents of this page and all the pages linked here are community developed pages. The core project team ensures the accuracy of the contents. What I found in that community was that we all added to each other's efforts. It works in that community.

The site is wide open...if you register an account, you can add content. I don't agree that is the best idea as it stands. I think "contributed pages" should have a big red bar across the top and indicate the contents have not been validated officially. Of course the idea is to validate/correct etc and remove the bar once validated.

All we need to do this is frontend permissions, a drop down selection with folder names to place a new document into, and a button to add a new page to the selected folder. The folder list would be limited to the document folders. Then we provide an rich text <textarea>. Folks with accounts, create documents rather than answer forum posts.

Are we getting anywhere with the decision makers?

[Ralph]

At one point I did some experimenting and here is what I remember from way back when... In order for a group of people to adequately contribute to the documentation, and to do so within Etomite, we need to standardize on a set of styles... My recommendation would be to try to primarily stick with good old-fashioned default HTML tags for styling, with a sparse minimum of custom styles...

RTE offers about as much as would be needed for basic documentation... The only downfall with RTE is that it doesn't offer the option of formatted markup - something I wish it could provide... But even not using an editor, or importing from a local editor would suffice... It's just a matter of continuity in formatting that we need to nail down...

Possibly the biggest concern is how to display code blocks without messing things up... I've tried several methods and am open to suggestions... Code examples are one of the most important resources we can offer those looking for help... We could write volumes and not get our point across nearly as easily as showing a few lines of working code... Cut, Paste, Modify, Test, Modify, Test, etc... That's the only way people learn...

I'd like to see documentation and tutorials combined because they go hand in hand... View the tutorial code and then dig into the documentation to see WHY things work as illustrated... Then the juices might start to flow and the synapses will start firing...

If Etomite can do these things, lets make it do them... If it can't do some of it, lets make it do these things...

Okay, I'm rambling now... I'm off to try a few things that came to mind while typing this...

[Cris D.]

I agree with Randy.

Please don't take any feedback for improvement the wrong way, I think your support is great but one thing that did turn me off at first was the size and number of threads organised by snippet or user query (in the main), made it very difficult to wade through finding stuff.

Also when thinking about your client base, in my opinion one of the main reasons anyone would go for a CMS is so more people (and less knowledgeable people) can have access to dynamic content on a web site.

That means in many cases the people looing at Etomite may know nothing (and if you know the staff I work with I mean NOTHING!!) about websites let alone coding syntax.

It is my understanding that originally Etomite was a place where coders could get together and work on a project, I think you have something much more than that now.

If you tailor some content to Newbies at a very basic level, perhaps catering to other learning styles aside from reading text (ie interactive tutorials, diagrams with visual representations (pictures) of what Etomite is and how the components can interact like chunks, snippets, API's etc), you will have more willing and able to wring the most from their installation and perhaps put back into the project.

The idea of answering questions in a forum means that the more questions you answer, the harder it gets to find info...(think about it). I think a centralised documentation space is the way to go too.

From a newcomers point of view,one of the most confusing things for me has been working out what is etomite language, what is generic php, what is SQL as well as the etomite functions that allow different methods of coding to to interoperate. Before etomite I had never used php, sql, had no idea what PHPMyAdmin was and a "database" was a foggy idea...imagine that! Having NO CLUE and stumbling across your web site! Perhaps even some samples showing what the different code styles look like, where to go for more help with this from the outset. (OK Ralph just said that).

I know it is usually a time/money issue and when I am familiar with Etomite enough, I will be willing to work on the above if required/ desired (having a background in adult education means I'm a sucker for this stuff).

Edited by Cris D., 21 April 2007 - 02:32 AM.

[lloyd_borrett]

G'day,

An interesting thread. In order to help solve the confusion about where to get snippets, it might be useful if the OLD snippet library page had some text that explained the situation plus links to the NEW snippet library area.

Likewise, it would be useful that if somewhere in the NEW snippet library there was an explanation and link back to the OLD snippet library.

I think it would even be useful to change the side menu to have Snippet Library (Old) and Snippet Library (New).

Simple explanations in a few places could make a number of historical issues like this a lot clearer to newcomers.

Best Regards, Lloyd Borrett.

[Randy]

Concur completely with Lloyd on this one.

[Cris D.]

Has any more thought been put into this one?

I wanted to do a tutorial for the creation of a snippet integrating custom made html forms using getfFormVariables, updIntTableRows(), putIntTableRows() and getIntTableRows() to display the data.

Robotarchie also has the same idea for templates. I'm sure that there are a number of qualified users who could provide step-by-step walk throughs.

My main concerns would be
1) consistency of layout,
2) accuracy of info (I expect that tutorials like this would only be made publicly available after approval be the eto admin to ensure accuracy),
3)Published format. What would the preferred format be? pdf? html? php?

Is it something that could be easily integrated into the Eto site?

Perhaps also a place for Ralph to roll over his tutorials to...

[jjj]

[quote name='Cris D.' date='May 27 2007, 07:54 PM' post='43065']
Has any more thought been put into this one?

My main concerns would be
1) consistency of layout,
2) accuracy of info (I expect that tutorials like this would only be made publicly available after approval be the eto admin to ensure accuracy),
3)Published format. What would the preferred format be? pdf? html? php?
-----------------------------------------------------------------
1- standard template. ?
3 - Not pdf, need to be able to copy and paste examples.

pdf would solve the problem of How to display example code. but I think that not being able to copy and paste would be a larger problem.

[cathode]

If anyone wants to contribute documentation, then can begin now by producing this stuff in good clean style-free html. Proper semantic markup needs to be followed... meaning to use h1, h2, h3, p, pre, etc. No inline styles or layout elements should be used - only content.

Once complete, these documents can be passed on to one of the core team members for approval and addition to the documentation section.

All documentation should eventually be placed into Etomite... i.e. regular HTML for placement in an Etomite document. That way the master stylesheet will take care of the look and feel.

When the new design arrives, having a special standardized template for documentation is an option if needed.

[Cris D.]

Here is my first tutorial. I didn't know who to give it to as I can't attach files in PM's.

http://www.etomite.c...mp;showentry=52

It describes how to create your own database table, html form and snippet to send data to a table in Etomite.

[Ralph]

Here is my first tutorial. I didn't know who to give it to as I can't attach files in PM's.

http://www.etomite.c...mp;showentry=52

It describes how to create your own database table, html form and snippet to send data to a table in Etomite.

I gave the tutorial a quick read through... Looking good... Like many of my tutorials it might not have enough substance for some readers but it gets people headed in the right direction... It would be helpful to hear from someone who has attempted to use the tutorial for guidance in getting a working form going... I tend to make adjustments so fast that I forget that what I did was undocumented...