Dataface docs progress

[Aoirthoir]

Ok I have read through EVERYTHING except for the weblite.ca stuff. I printed all of that yesterday though. Of course I dont remember all that I read, but I have a much better handle on what is happening. There were lots of code examples, suggestions and so on. A lot of it was from before v0.6 so some of it is deprecrated or inherent now in DF.

When I was going through the weblite API DOCs site yesterday I got a lot of good ideas from its presentation. Some of it will fit in well with what I have already. (Obviously am excited about the code for that being released). I would like to be able to have a comments box as appears on there, for everything on our docsite. With the ability to have a valuelist for categories, based on SQL. This would have things like CODE SAMPLE, SUGGESTION, etc. I'll start to review that when the code is released so I can implement it.

Now if you go over there you will see the records list on the first page are displayed just as an ordinary web page. They do not have the "DFlist" look to them. I like their setup. It displays records using a Dictionary List. Unless Mr. Steve cranked this out by hand, the code for this would be very useful in the future. This is how I want our docs to eventually appear. For the meantime I just want to get them into a normalized DFbase. This will allow a LOT of cross reference. I will use my R_ table multi to multi relationship setup, unless someone has any better ideas. Mr. Steve is working on an AJAX tree so that way, we will be able to always drill down easily.

Right now I wont be working on things like tutorials, handbooks etc. Those I plan to be put together from relationships of all the info in these DFBases that I will create. A user should be able to go in, if they find an item of interest, add it to their own handbook. A user should be able to add comments, and code samples, questions, resolutions, to any item. Thus the reason on waiting for the tutorials.

Now the exact format for these DFBases I am working on in my mind. So we have to ask what needs documented. Ok well there is a lot already documented. So maybe, what needs organized, with samples, and so on. In short everything.

So we need docs on INI files/settings/usage etc, Delegate Classes, Permissions, SQL, Triggers and on and on. I want a way to link one request/problem to multiple solutions. So if there is a way to do something in SQL, Triggers, Delegate Classes, Custom Smarty Templates, and so on, I want all of those to appear in the list of solutions for that question. Now this doesn't mean I want to figure out multiple ways of doing something. Rather, as in the forum, different people offered different solutions for a particular problem. So if Steve has one method, he can post it in the question. If I have another it can be posted. If NJW has a problem, it also can be posted. Since it will all be relation based, if mine is SQL based, and someone wants to see all the SQL solutions, well there mine would be. If it was ini setting based for the fields ini, then it would appear under the fields.ini section. It would also appear under ini settings section. And of course any other section we create.

So rather than creating fifty thousand tables for this...one for the ini info, another for the css, and so on...I wish to create a generic series of tables. Perhaps. Others may have better ideas, which is why I am posting this, to get some feedback.

Ok going to take a break and relax, then think some more and add to this...any ideas are definitely most welcome.

[njw]

Have you had a look at the way the MySQL manual is done online. That's a useful structure - the actual manual can be pretty opaque at times, but that's down to the author! The ability to have the documentation page followed by comments is useful, as is the idea of tagging.

Just a thought

Neil

[Aoirthoir]

I will take a look at the MySQL manual, it has been a while. What do you mean tagging? And I like the idea of comments. If you go to http://dataface.weblite.ca/ you will see the basics of what I am thinking for the structure. This is somewhat similar to the MySQL site (I just had a look at it). Using the new tree format we can have the "references" appear..but then actually do what you talked about in the email about docid and such. Also you can have self relating tables in straight dataface (see below). I am using that format currently with my mini-project manager and it works great.

Basically what I am thinking of is Article "Tidbits" which would be as small as a line or two. These tidbits are just records in a table. Combine several records and you have a paragraph. Combine these and you have an article. So for instance like this:

INI Files (description..comments..questions..whatever other fields we want...) one record
-->files.ini description..etc..another record
-->valuelists.ini (another record....)
-->conf.ini (another record..with description of conf...)
---->ini category...(links conf.ini to its headings)
------->[_database]another record
----------->settings (links [_database to its settings)
--------------->host (another record)
--------------->name (another record
------->[_tables] another record

Now that is the internal structure, possibly using just 2 tables. One table for the actual records perhaps:

ID (int...etc)
Title (varchar 50? something..)
Description (varchar 250?)
Comment TEXT
(more fields...perhaps about author...dates..changes..df version...so on)

These are linked using an R_ relationship table

PNAME -ParentTableName
CNAME -ChildTableName
PID -ParentID
CID -ChildID
OID -order ID..for moving records up and down in a relationship..currently I cannot get it to work with this R_ table but in ordinary relationships it does work.

This relationship table allows for many to many relationships across many different tables including self mapping relationships...and using the new tree list in dataface it allows RECURSIVE relationships. We would modify it a little bit to fit your excellent suggestions (which have me very excited..) about the Who, Comments, dates and so forth. Or we would link to a third table containing that information. Or, just put that information directly in the Doc Tidbit table(not its name just a description).

We have to examine exactly how to do it...I want folks to get credit not only for their tidbits, but also for their "editing?". That is...if someone spends time linking tidbits into various articles... since one tidbit might be used in many places. They should get credit. So having author info just in the tidbit section isnt enough..it has to be in the relationship section.

The reason I want to use the tidbits..is since one item might be used in many places..it allows us to create step by step instructions just by adding items to a relationship.

So if I quote your email.....you have spelled it out more fluently:

Doc: Intro to Permissions

Related Docs: Delegate classes; Implementing Record Selection; hiding unavailable tables....etc

Which then would each have...their own additions perhaps.

So an article is a combination of tidbits, and those are combined and so on upstream.

However....we want the "presentation" of them to not appear this way. So in our editing mode, yes we would see records and so forth. We would see relationships again...and so on. But in view mode, to read the docs...that we our others have put together combining these tidbits..it should just all flow in a stream down the page and appear to be a normal webpage...Hope that makes sense



As to the tidbits...

First things in dataface that should be documented:

Classes
Methods
Variables
Tags?(see dataface.weblite..its under methods)
Parameters
Functions
Templates
Blocks
Slots
Macros
Ini Files - and each INI file..and custom ini files/settings
Ini headings
ini settings/values
delegate classes
triggers
css
sql
actions
error messages

Second additions and ways of documenting:

examples
comments
questions
suggestions
bugs
requests? (suggestions?)
Files
screenshots.
links?
caveats
best practices
avoidances (things to avoid)

Further comments are definitely appreciated. Once Mr. Steve releases the code for dataface.weblite.ca I will probably have more ideas.

[Aoirthoir]

One note about tidbits...

They do not have to be tiny. If someone wants to list an entire article...in one item, they will be able to do so since we will be using the Comments area as TEXT..however comments is usually what I call that field in my tables..I think we have to call it something else...will get to that later..

[njw]

Tagging is like the tags in del.icio.us - attaching single word tags that describe what the article is e.g. the tags I used for Dataface on del.icio.us were:

Opensource
MySQL
development
PHP
framework

Each of these are little indexing items that get you a collection of references on del.icio.us to web sites.

I was suggesting something similar for the documentation, although the implementation might be a challenge and it may be a bit over the top for now.

Neil

[shannah]

Implementation wouldn't be difficult at all.. sounds like a good idea.

-Steve

[Aoirthoir]

Ah I like tagging! Excellent then. Would that require a change to DF then or just something we have to set up in our DF apps?

Is there a way to search across files yet? So would these tags just be in a comment field? or would each tag be its own record linked in a many to many?

Not sure how exactly to implement it...but it is a great idea.

[njw]

To keep the data structures normalised - and to make it easier to prevent misspellings - the tags should be in a table

TagID
Tag Name

And then a joining table can be built:

ID
RecordID
TagID

You could use a multi-value field, but then searches would be more complex and a lot slower.

Neil

[Aoirthoir]

Mr. Neil,

I definitely like the idea of keeping everything normalized, and keeping everything truly in the right categories/tags.

Ok so that brings up some things. I use the R_ table and structure above because I dont like having either long table names if I can avoid it, or having to create a new table every time I want to refer one table to another table. It gets really frustrating. So my R_ table basically handles that. (I'd actually like to see a method of simply incorporating that into DF itself, so that, to specify a relationship one just has to state the table and the type:

in app/tables/D_CUSTOMER/relationships.ini:

Code: Select all

[D_ORDER]
type = m2m


(or 121 or m21 or 12m...)

You get the idea I hope, some kind of notation to specify what kind of relationship it is and then in the background DF would just update the R_ table..or whatever table Mr. Steve chose to use...and whatever fields, merely giving a .sql file with the create table code so we could incorporate it into our sites....Because again, just as the process to view a table is always the same, so too a process to connect a relationship is usually the same. Actually the relationship table could be specified in an INI...as well as which fields to use for the relationships...so if someone does not want to use the Pname/CName functionality, and instead what separate relationship tables..they could do so..and not be locked into my methodology.

However we dont have that now so we just create the following code in app/table/CUSTOMER/relationships.ini:

Code: Select all

[D_ORDER]
__sql__ = "
SELECT * FROM R_, D_CUSTOMER
WHERE R_.PNAME='D_CUSTOMER'
AND   R_.CNAME='D_ORDER'
AND   D_ORDER.ID = R_.CID
AND   R_.PID='$ID'"


Actually not that much more work honestly. But each time I have to change the table names and make sure I dont forget. The code prior would be a lot easier to change, only requiring specifying the [TABLENAME] and it could be repeated throughout our app..even in a central relationships.ini if we wanted like this....

[PARENTTABLENAME]
childtable = m2m
anotherchildtable = 12m


Then as it does with the table reads, and other relationships, DF would take care of the more complex relationships. Not all of course but a great many of them could be handled off the rip this way.

Currently though, while we have to do it by hand, what we have is the ability to link many tags to many tidbits and many tidbits to each other and to many articles and many users and so on...

Ok as usual I went on...and on...so let's boil it down to the tables we need.

User
ID
SignOn
Password
NickName (what is displayed)
FirstName
LastName
Comments
???


Docs
ID
Title
Description? (longer than the title...text field but not htmlarea...)
Content (htmlarea?)

Tag
ID
Name

R_
ID (usually I just use the below fields as the PRI..but this would probably be better)
PName
CName
PID
CID
OID (order)


So then, should each of the areas, INI files, Triggers, Delegate Classes, etc simply be within the Docs table? Also for reference...I like to use the table.column way of identifying information rather than table.TableField method. It just looks cleaner to me. Thus the reason for the above names. So we need other fields I know....date, time etc...some way to track changes...the history thing which I still havent gotten to would suffice...or better with your single field thing..although, saving the entire record makes undos a lot faster currently, since we have to do them by hand. If we have an automatic facility in DF to do so..or it is part of a delegate class, then it should not matter having the changes only to a field saved, as you suggested a while ago.

Now looking at your tables from the email it is very similar. With the exception that I am making all relationships many to many with my R_ table above. Ok why? This will allow me to see ALL links to ALL tables to ALL records from any specific table/record or to any table/record. So when I want to look just at the straight SQL outside of DF, I can do so and see all my relationships. This will allow me to create a true tree link setup. Both in and out. It does take up more storage though, I realize that. I've not had any hits on speed as far as I can tell. So I think the extra information provided is worth the extra cost.

Now though, I do not know for instance if the DF Documentor separates these things out into different tables or keeps them all in the same table.....We can certainly separate if we want..there are different pieces of information stored for an INI file reference than stored for an API references....a lot of the differences though are just m2m and are in other tables already...no need for extra fields.

Comments most certainly sought. Any ideas about other tables or additions to those tables?

Thank you kindly

[Aoirthoir]

Ok, thinking about it, some of the docs should be in their own tables....though still linkable in a non-intrusive manner..or perhaps extra info tables..linked into the entire caboodle...

Such as the ini files. A lot of settings are going to be the same...so as Mr. Neil said with the tags, we want ini settings to be normalized....so they should be in table..it also prevents mispellings...


Some things of course are a bit complex and freeform to be normalized..delegate classes might or might not be..they would probably just link to the API tables..or tidbits...

Thank you kindly.