Pliant talk forum

Pliant talk forum

Discussion: Cards

Discussions to determine the functionalities
requested for documentation cards.
Message posted by pom on 2003/06/15 08:52:13
The aim of the documentation card-programming is to generate as much
documentation as possible automically and to check (whenever possible)
the compatibility of the documentation with the actual code.

Navigation should be generated automatically from relation declaration.
Thatfor, it appears that one should be able to declare links either from
the source card, or from the target one. The links should be gathered in rubrics
to allow a nice display of navigation alternatives.
Declaration of links from target to source card might be done using "connectors"
declared in the source card.

Some elements of the card should be "accessible" without a need for an actual
HTML generation: title, rubrics and links.

Cards might be "generic", a bit like virtual trees (some code might apply
to document several types, aso). Links should be also defined genericaly.

Special controls:

  - type, function, ... description: it should be possible to sometimes retireve it from the source code
  - syntax definition: it should allow the possibility for the definition to be defined by the function, method or meta itself.
  - sample code. Might be shared between several controls. Should allow execution (when permissions are set accordingly)
  - configuration (configuration page for an application)

Message posted by hubert.tonneau on 2003/06/15 14:28:51
This discution is probably just ... to early.

What I plan to do is add very basic functions to handle cards, then start
writting a fiew of them, and check if I can succeed to write usable (up to
date and complete) low level documentation that way.

Then if, and only if, it prooves to be a valuable documentation mechanism
for me, I will look at some extra tools to help me handle a large set of
these.

On the other hand, I don't want to start thinking about advanced tools in this
area right now, just because it would disturb me from the main goal: write.
Message posted by pom on 2003/06/15 18:13:07
I understand your point of view.
Both views are not really opposed to each other: you want to be able to write
down small cards to give your knowledge, and I plan to study an overall
architecture allowing a real documentation scability.
I have had many discussions with people from knowledge managment and the
conclusion is that a bad architecture leads to at least quadratic space
when linear space is needed, or even exponential space for very bad low level
choices. This does not only affect disk usage, but also maintanability,
coherence, aso.

Thus, the same way you are concerned with the scalability in most of Pliant
applications, the same should apply to documentation. The interest of discussing
the main requested features now would be to validate some high level views
and low level implementations allowing an efficient implementation of these.
Message posted by pom on 2003/06/15 18:26:33
To be more specific and more "low level", here are some important issues,
in my own (humble) opinion:

- information sharing: it goes from the reuse of some blocs of text down to
  the embedding of dependent values in a way that they should be recomputed
  the same way constants are.
- linking reduction: when you have a big amount of cards with high connectivity
  (for instance, consider the extreme case where each card is linked to each
  other one), the size of the data representing the linking should stay as linear
  as possible (or at least around n log n). A simple way to do this is, for
  instance, to gather all links in totaly linked parts into stars with an extra
  central virtual node.
- virtual cards management: as soon as some part of the documentation may be
  generated online (think about basic type documentation) in order to reduce the
  amount of used memory, some cards should be able to represent a parametric 
  family of cards, the same way virtual trees represent an orborescence.
- cards (and even all the documentation ressources) should have some URI.
  The architecture of the path assigned to a card highly depends on the way
  the main arborescence scheme is viewed.

- cards should easily be edited and linked to each other. The point is
  that you cannot consider an overall knowledge of the documentation
  each time a card is inserted. Thus, categorization and linking helps
  should be implementable (even if not implemented in early stages).
Message posted by marcus on 2003/06/15 19:35:32
In my (very humble) opinion, the low- and high-level functionalities you have
mentioned are great. But I fail to grasp how the actors (using the OO analysis 
lingo) in this documentation cards system would use it.

That is, from the view point of the actors, which functionalities would
they perceive when using the system? Perhaps some of the functionalities
pom mentions are not perceived by an actor, but are built in the system's black-box.

In pom's vision, the systems seems to consist of three sorts of actors:
- documentation writters (Hubert, for instance)
- automatic documentation creator (mentioned in pom's message), and
- documentation readers, i.e., someone navegating through the documentation.

In Hubert's vision, it consists of only two: the writter and the reader.
Message posted by pom on 2003/06/15 20:05:03
Some possibilities:


Percpetion by a writters:

 - gathering: a file is a set of cards
 - typing: most of the cards have some "type": syntax, sample, explanation, aso.
 - connections: cards may export "connectors" to which other cards.
   Each type might have its own predifined declaration meta for reendering.
   may connect themselves; some cards may even be reduced to a connector
 - index and hierarchies: keys may be used to give some hints for connections
   between cards; indexes may be generated.
 - "low level" functionalities to retrieve some info from source when available,
   and to know if they are available
 - A set of high level cards or connectors for applications interface
   (for configuration, link to application, logs, doc, aso)

For editors:

 - possibility to edit cards for correction, or to type a translation
   with a view on the original card.

For users:

 - automaticaly generated navigation frame (thus customizable),
   (for instance: general to specific, user view to source code,
   transversal navigation, like "see also")
 - bookmark and annotation handling, possibility to mark a set of cards to
   gather it into a single page for printing,...
 - possibility to add some new cards realizing with new connections between 
   cards (for instance to build a course gathering some topics) with simple
   text, which would be saved in a private databse file, for instance
 - possibility to extract a set of cards for a master card to document
   some specific application (and maybe its internals) down to some
   specified level of details.
 
Message posted by hubert.tonneau on 2003/06/15 20:28:16
It's even more trivial: I don't have the available mental ressources required
to follow Patrice at the moment.

Basically, It suddenly got clear to me a fiew weeks ago what the second generation
web would be (you can think about it has what Pliant ultimate user interface
will be), so I have to adjust all the existing parts to the new overall
picture, and it has been an exhausting task in the HTTP server area (again,
read it as existing user interface) because I also had an Heliogroup driven
time constrains.

So, what I say is my agenda for this summer is already closed:
. there is the single cache mechanism that must go in release 86 because with
  the very high level of service Pliant is now carrying (fonts, cached images,
  cached sub databases, etc), we cannot bound the memory consumed properly
  (so keep servers reliable) without it.
. I want to take time to thing about the second generation web because I want
  to have a running propotype within a year.
. so it's the right time to move back to slowly documenting existing areas
  because I know they will not move much for some time, and I've delayed already
  too long (who nows how the Pliant great photos editing and printing tool works,
  or even that it does exists).

Also I plenty agree that Patrice can build a prototype in order to demonstrate
his view, then we will convert some of the existing cards, and try to get
the highest raw productivity for Hubert, and best connection with Marcus high
level documentation since Hubert documentation is now only expected to be raw
materials Marcus picks to build more elaborated one.
Message posted by hubert.tonneau on 2003/06/15 20:38:15
Patrice, the key difference between hour view is that you seem to see the
documentation I'm going to write end user centric, whereas I see it as
Marcus centric.

So, what I want to first do is maximize my words per hour rate, then adjust
in order to make is as easy as possible to use for Marcus.

I would even plenty agree with the fact that the cards I write would be
temporary, just waiting for Marcus to build something consistent for each
part. So I need no serious tool. Marcus might.

Also, there is your idea of self generated documentation that I've lost in
this picture, but I'd prefer you to sell it to Marcus than to me because
Marcus is the leader of the documentation part.
Message posted by hubert.tonneau on 2003/06/15 20:51:59
Marcus,

Patrice suggestion is raising a crazy idea to me:
Why not switch to an interview model at my level ?

I mean, we open a special documentation forum, then you just open there some
debates asking for informations about various parts, and I answer as fast
as possible without trying to make the overall consistent.
So, you can ask more details when my first answer does not fit properly your
question and so on, and you can have several pending questions at once.

Then, you can efficiently put this raw material to something consistent because
you know the general framework of the documentation and since you asked the
questions, what I'm writing remains tightly related to your needs.
Message posted by hubert.tonneau on 2003/06/15 20:54:58
In other words, this basically means Marcus writes the subject of each card,
and asks for extra details (you could think about it as card patch) until his
got all the materials about the subject.
Message posted by marcus on 2003/06/16 13:17:20
I like Hubert's special documentation forum idea.

I have some canditate discussions (debates) to start the forum, all themes of 
future howtos:
- how to Web styling in Pliant
- how to remotely execute code in Pliant
- how to (and when to) metaprogram in Pliant
Message posted by hubert.tonneau on 2003/06/16 13:52:56
Ok Marcus, the documentation forum is open at:

http://pliant.cx/pliant/browse/forum/pliant.doc/
Message posted by maybe Marcus on 2003/06/20 01:14:05
Hi Patrice,

To be able to update the .page documentation, I need a doc.style compatible with 
release 85. 

Could you provide this doc.style for us?

Thanks.